5 Policy Manager API

The Policy Manager API provides programmatic access to most of the functions in the Policy Manager user interface. You can use the Policy Manager API to create and manage policy domains and their contents. For example, you can write applications that use the programmatic interface instead of the GUI to create, modify, delete, and retrieve policy domains and their contents.

This chapter explains how to write applications that use the Policy Manager API. The following topics are discussed:

• How the API works.

• The source and header files for the API and describes the build process.

• Some of the methods common to most classes which are included in the API. This section discusses the ObAccessManager class. This section lists and describes the content of Access Configuration and Access Policy classes. It describes the Test classes that you use to perform access tests against one or more users whose information you specify. The section concludes with a discussion of the ObAMException class, which is used for error handling.

• The classes that make up the Policy Manager API and gives examples of the class definitions in the Java programming language, managed code for C++, and, in some cases, the C programming language. For some classes, code samples are included to show how objects of the class are created and how methods of the class are used to act on those objects.

This chapter contains the following sections:

• About the Policy Manager API

• Development Environment

• Coding With the Policy Manager API

• Policy Manager API Classes

5.1 About the Policy Manager API

The Policy Manager API provides an interface which enables custom applications to access the authentication, authorization, and auditing services of the Access Server to create and modify Access System policy domains and their contents. Before using the Policy Manager API, see the Oracle Access Manager Access Administration Guide. To better understand the functions provided by the Policy Manager API, explore the Policy Manager GUI.

The Policy Manager API provides Java, C, and managed code bindings for classes which you can use to instantiate these objects:

Access Policy Objects: These objects are used for data that is part of policy domains, policies, access conditions, audit rules and other policy domain content that Access Administrators ordinarily configure through the Policy Manager.

System Configuration Objects: These objects are used for data that is part of Authentication Plug-ins, Authentication and Authorization Schemes, and other policy domain content that the Access System Administrator ordinarily provides through the Access System Manager in the Access System Console.

Some system configuration objects, including authentication and authorization schemes, the master audit rule, and host identifiers, are exposed by the API as read-only objects. You can use these objects within your programs just as you would use their corresponding Access System components. For example, just as you cannot modify an authentication scheme from the Policy Manager, you cannot modify an authentication scheme object using the Policy Manager API.

Access Server Connections: The ObAccessManager class represents one or more connections to Access Servers hosting the Policy Manager Service. An application uses ObAccessManager methods to send requests to get and set policy objects and to get configuration objects (setting of configuration objects is not supported in this release).

The following two diagrams show the structure of the Java and C bindings for the Policy Manager API.

In both cases, communication between the Access Client and the Access Server is provided by the Transport Protocol.

5.1.1 Notes on Managed Code

In the following sections, managed code examples are depicted as managed C++. However, managed code can be written in any language supported by the Microsoft .NET managed code framework.

The managed code API resembles very closely the C and Java APIs. Classes and method names between the APIs are very similar. Here are some of the key differences:

• The C enumerators used to specify various conditions are wrapped by managed classes.

• Certain method names have been changed to match the naming conventions for properties. A property is similar to a member variable in that it enables the user to read and write values to an object. However, the property is implemented using get and set methods.

All managed class names are appended with the Mgd tag. Managed helper classes are documented in Appendix F, "Managed Helper Classes".

5.2 Development Environment

The Policy Manager API is a subset of the Access Manager Software Developer's Kit (SDK), which also supports the Access Manager API. This section describes the structure of the installed Access Manager SDK directory and subdirectories, and describes the initial steps in the build process. See Appendix D, "Installing the Access Manager SDK" for installation process details.

5.2.1 Installation Location

The Access Manager SDK is packaged as a product distinct from the Access Server, and must be installed in a separate step. Oracle recommends that you install the SDK on the same system that will run the application you want to build using the API. Note the location where the SDK is actually installed. The installation location is needed as part of various path definitions to be set up later, and is called sdk_install_dir in the rest of this chapter. For example, for the Windows programming environment, you might specify the following path as the installation directory:

C:\COREid\AccessServerSDK

Note: The Access Server is distinct from the Access Manager SDK and installs in a different default location. See Chapter 6, "Authentication Plug-in API" and Chapter 7, "Authorization Plug-in API" for information about the APIs you can use to create custom authentication and authorization plug-ins.

5.2.2 Installation Content

Within the installation directory, the following directories and content are provided:

apidoc: Provides online documentation for the Java version of the API in HTML format. The documentation describes two distinct packages. First of these is com.oblix.access, which is used by both the Policy Manager API and the Access Manager API; see Chapter 4, "Building AccessGates with the Access Manager SDK" The other is com.oblix.accessmgr, which is used only by the Policy Manager API.

examples: Includes a sample build file and sample make script, and example applications in subdirectories. The subdirectory obaccess contains an example servlet, and prototypes for classes that can be used to extend the startup and shutdown classes for the server application.

include: Contains header files that define the classes, methods and functions that make up the C++ and C classes for the obaccess library. In particular, the obaccessmgr_api.h file contains the descriptions for the Policy Manager API C functions.

oblix: Holds these five subdirectories and their contents:

apps: Contains the netlibmsg.lst file of messages available to the AccessGate if errors occur. This is located in the path common/bin. At the discretion of the AccessGate, these could be logged locally (if the AccessGate has been configured to maintain a log), displayed locally, or ignored.

config: Contains nothing, immediately following installation. When you run the configuration tool and set the AccessGate to run in simple or cert mode, configuration data for the AccessGate is stored here. This includes an encrypted password file and the random seed for the key used to do the encryption. If the connection to the Access Server is secured, then Public Key certificate data is also provided in this directory.

lib: Contains the Access Manager SDK libraries and Java archive files that are built into the application.

• Various library files: Contain the libraries required by the API: obaccess.dll for NT and Windows 2000, obaccessmgr.so for Solaris and for AIX, and obaccessmgr.sl for HP-UX. Each of these libraries contains the complete implementations of the policy and configuration objects and the ObAccessManager. The ObAccessManager uses methods from the aaa_client library appropriate to each platform to communicate with one or more Access Server(s) hosting the Policy Manager Engine(s).

  The obaccess libraries also contain the policy objects, get functions for some of the configuration objects, and a subset of the ObAccessManager functions. The libraries also carry the native side of the JNI interface used by the Java binding.

• jobaccess.jar: Is the Java archive file for the API. It contains two packages, com.oblix.access and com.oblix.accessmgr. Some methods from com.oblix.access are used by the Policy Manager API to communicate with Access Servers.The com.oblix.accessmgr package contains all other Policy Manager API methods.

• ObAccessGate.msg: Provides the text of messages that the AccessGate may need to display.

• ObAccessClient.xml file: An example of the configuration file that is used by the AccessGate. For details on the contents of this file and modifying an AccessGate, see theOracle Access Manager Access Administration Guide.

orig: Contains information created during the installation of the SDK; this directory can be ignored.

tools: Contains three significant directories:

• configureAccessGate directory: Contains the tool used to configure the AccessGate and the messages needed by it.

• The migrationtools directory: Contains information useful for migrating earlier versions of the API.

• The openssl directory: Contains a tool and certificate file used to configure the AccessGate for simple or cert mode operation.

samples: Contains versions of the standalone Access Test application, in Java, C, C++ as well as example Policy Manager API applications. You can use these applications to become familiar with the SDK build process before going on to more complex applications.

Note: Do not change the relative locations of the subdirectories and files within the SDK once it is installed. Doing so may prevent an accurate build and proper operation of the API.

5.2.3 About Building an AccessGate

Before you build your application that implements an AccessGate using the Policy Manager API, you must set or modify certain environment variables.

5.2.3.1 Environment Variables

To ensure that API components can be located, you must set certain environment variables before you compile the application that uses the API. See the discussion in "Setting Environment Variables".

5.2.3.2 Build Process

Sample files to create servlets and build JAR files are provided at different levels within the examples directory. See"Installation Content".

5.2.4 Configuration File

The AccessGate you build with the API must be properly configured or it will not be able to interact with the Access Server. You configure the AccessGate by defining the content of a configuration file on the system where the AccessGate is running. A discussion of the content and use of this file, and modifying an AccessGate, is in the Oracle Access Manager Access Administration Guide.

5.3 Coding With the Policy Manager API

The Policy Manager API provides functionality equivalent to that of the Access System's standard Policy Manager user interface. The API includes classes to represent and manage the same data objects managed through these user interfaces.

Access System Configuration Objects: Represent data managed through the Access System Console, including authentication and authorization schemes, host identifiers, resource types, and the master audit rule. Discussion of these objects starts at "Access System Configuration Objects".

Access Policy Objects: Represent the data managed through the Policy Manager GUI, including policy domains with all their subordinate information: policies and authentication, authorization, audit, and administration rules, and authorization expressions. Discussion of these objects begins on "Access Policy Objects".

The ObAccessManager Class: Provides a way to connect to the Access Server and to create, retrieve, modify, and delete Access Policy objects, and to retrieve Access System Configuration objects. This class also provides methods to test access policies. Discussion of this class starts at "ObAccessManager Class".

Exception Classes: Provide methods for capturing and presenting errors that may occur. Discussion starts at "Class ObAMException".

5.3.1 API Conventions

The Policy Manager API follows the object-oriented programming concept, in which classes define objects and methods, and the methods in the class operate on the content of the objects.

The Policy Manager API classes are implemented in the Java programming language and as managed code classes. The Policy Manager API also includes an equivalent C programming language implementation. Definitions of the classes and functions for the supported languages are provided in Appendix B, "Policy Manager API Definitions".

Note: In the examples of this chapter, the managed code is appropriate for managed C++. However, keep in mind that you can write managed code using any language supported by the Microsoft .NET framework for managed code, including Visual Basic, C#, and C++.

5.3.1.1 Programmatic and Implementation Conventions

In Java, methods are called by reference. The application knows what class the object was created under and therefore which method to use. For example, to first create an authentication rule named myauthrule, and then set a description for it, you would write the following code in Java:

ObAMAuthenticationRule myauthnrule = new ObAMAuthenticatonRule[];
  myauthnrule.setDescription(ÒThe description textÓ);

For managed code, how the methods are used depends on the implementation language. For example, to create an authentication rule and a description for it, you would write the following code:

ObAMAuthenticationRuleMgd *myauthnrule = new
  new ObAMAuthenticatonRule();
  myauthnrule->Description=ÒThe description textÓ;

The C implementation mimics the Java operation by the extensive use of opaque pointers to an underlying set of structures. (Fortunately, you need to deal with only the top layer of these.)

Classes and objects are referenced by pointers to their structures. When an object is created, the returned value is a pointer to a structure defining that object. The pointer type is always the object's class name with the text _t appended. When you use a C function to change a member of the structure for the object, you include the pointer as an argument to indicate which object you are referring to.The pseudo-method name used to make the change is precisely defined by preceding it with the class name of the object whose structure is being modified. In C, to create an Authentication Rule named myauthrule and set a description for it, you would write the following code:

ObAMAuthenticationRule_t myauthnrule;
  myauthnrule = ObAMAuthenticationRule_new();
  ObAmAuthenticationRule_setDescription(myauthnrule, ÒThe description textÓ)

5.3.1.2 Naming Conventions

To the greatest extent possible, classes, objects, and methods all have names that describe what they contain or what they do. For example, the class ObAMAuthenticationRule provides methods for manipulating Authentication Rule objects. In this class, the method setDescription is used to add a description for an Authentication Rule object. The ObAMAuthenticationRule class can have associated with it actions to be taken depending on the outcome of the authentication process.

The ObAMAuthenticationRule class inherits automatically the abstract class ObAMObjectWithActions class, and it uses its methods of this class for dealing with actions. As do the methods of most classes, those of the ObAMObjectWithActions class also have meaningful names. Any class that uses actions inherits the ObAMObjectWithActions class. For this reason, the names of the methods of the ObAMObjectWithActions class are general. For example, this class includes a method called addActionofType.

5.3.2 Creating New Objects

Each class has a method which acts as a constructor to build an empty object of the class. Java uses its built-in new() method to do this and the new object is manipulated by reference. The C version of the constructor is named after the object to be created with the text _new appended. The constructor returns a pointer, whose type is the object's class name with _t appended.

For example, to create a new Policy object in Java you would write the following code:

ObAMPolicy mypolicy = new ObAMPolicy();

In managed code, to create a new Policy object in managed C++, you would write the following code:

ObAMPolicyMgd * mypolicy = new ObAMPolicyMgd();

and in C you would write the following code:

ObAMPolicy_t mypolicy;
  mypolicy = ObAMPolicy_new();

5.3.3 Copying Existing Objects

Each class has the equivalent of a copy constructor that makes a copy of an existing object of the same class, including all its members. In Java the clone() method is used to copy an object, and the new object is manipulated by reference. Be sure to cast the cloned object to the right class.

The equivalent C function is named after the class, with the text, _copy, appended. The function returns a pointer to the new object. The function takes an argument that is the name of the object to be copied.

For example, in Java to make a copy of an existing action object called action1 and to call the new object action2, you would write the following code:

ObAMAction action2 = (ObAMAction) action1.clone();

In managed C++, you would write the following code:

ObAMActionMgd *action2=(ObAMActionMgd *) action1->Clone();

In C you would write the following code:

ObAMAction_t action2;
  action2 = ObAmAction_copy(action1);

5.3.3.1 About Cloning Objects Explicitly

To clone an object, you must copy it explicitly. For example, you cannot set a new value for an existing object and presume that by adding the object to the policy domain it will be cloned. The following snippet of code attempts to implicitly clone a resource object called resource1.

ObAMResource resource = new ObAMResource();
  resource.setResourceType(ÒhttpÓ);
  resource.setHostID(Òhost1Ó);
  resource.setURLPrefix(Ò/myresource1Ó);
  domain.addResoure(resource);
  resource.setURLPrefix(Ò/myresource2Ó);
  domain.addResource(resource);

The Access Server interprets the code as an attempt to change the URL of the first resource from /myresource1 to /myresource2. The resource object called resource has already been added to the policy domain. Rather than clone that resource, the Access Server interprets the following line of code as instruction simply to change the URL of the resource:

resource.setURLPrefix("/myresource2");

When the last line of code attempts to add the same resource again to the domain, the Access Server reports that it already exists.

The correct way to accomplish the intended task is to create a copy of the object and change the current values of any of its properties as required. Here is an example of how you might clone an object. This snippet of code attempts to add two resources to a policy domain. The second resource to be added is of the same type and has the same host ID as the original one.

ObAMResource resource1 = new ObAMResource();
  resource1.setResourceType(ÒhttpÓ);
  resource1.setHostID(Òhost1Ó);
  resource1.setURLPrefix(Ò/myresource1Ó);
  domain.addResource(resource1);
  ObAMResource resource2 = (ObAMResource) resource1.clone();
  resource2.setURLPrefix(Ò/myresource2Ó);
  domain.addResource(resource2);

The programmer wants to add a resource of type http whose host ID is host1 and whose URL is /myresource1 to the policy domain called domain. The code creates an object of type ObAMResource called resource1, and sets its values. Then it adds resource1 to the policy domain (domain).

After adding the first resource to domain, the programmer wants to add another resource of the same type (http) that is on the same host (host1). The URL for that resource is /myresource2.

For this purpose, the developer clones resource1, creating an object called resource2, which inherits all of the properties of resource1.The only property the developer changes is the URL. The developer sets the URL for resource2 to /myresource2.

5.3.4 Deleting Objects

Each class provides the equivalent of a destructor that deallocates memory used for an object, including member objects.

Note: Member objects are other objects that the primary object contains. For example, AdminRule objects contain Identity objects.

Java does not actually use destructors but rather garbage-collects objects that are no longer referenced.

Managed code is similar to Java in its use of a garbage collector. When an object goes out of scope and it is no longer referenced, it is automatically deleted.

In C, a specific function is used, which is named after the class to which the object belongs and which has appended to it _delete. The function takes one argument, a pointer to the pointer to the object to be deleted. The multiple levels of pointing are used by the function first to deallocate memory for the object and then to reset the object pointer to NULL after the object has been deleted.

For example, in C to deallocate an existing action called actionname from the ObAMPolicy class, you would write the following code:

ObAMPolicy_delete(&actionname);

5.3.5 Managing Data for Single-Valued Object Members

Objects can contain members having single-valued data members, and they can contain arrays of data or objects. For example, a policy domain can contain arrays having multiple resources (an array of objects) and multiple operations (an array of strings) for each resource type of a policy.

This section explains how to manage objects which contain single-valued data members.

5.3.5.1 Setting Data for Single-Valued Object Members

Each class has methods beginning with those that set the content for single-valued members of objects in the class. For these cases, the data is a string, integer, Boolean flag, or a reference to an object. The method name is always setwidget, where widget is the type of information to be set. In Java, the new data for the member is set by reference, and old data for the member may become eligible for garbage collection.

In the managed code API, any set method that takes only one value is used as if you were directly accessing the data member. For example, to set the description in the ObAMAuthenticationRuleMgd class, the method is treated as if it were a data member:

myauthnrule->Description = "The description text";

C is a bit more complicated. The first use of the set method stores a reference to the source object. Subsequent use of set for the same source object copies from the source to the receiving object member. The C function always takes two arguments. The first argument is always the name of the object for which data is being set. If the function is inserting a value, then the second argument is that value. If the set is inserting a reference to an object then the second argument is the reference.

For example, the code to set the value for a resource type (a string) and to add an authentication rule called myauthrule1 (an object) in an existing policy called mypolicy looks like this for Java:

mypolicy.setResourceType("http"); mypolicy.setAuthenticationRule(myauthrule);

And like this for managed C++:

mypolicy->ResourceType="http";
  mypolicy->AuthenticationRule=myauthrule;

And it looks like this in C:

ObAMPolicy_setResourceType(mypolicy, "http");
  ObAMPolicy_setAuthenticationRule(mypolicy, myauthrule);

5.3.5.2 Getting Data for Single-Valued Object Members

Each class has get methods that are used to retrieve the content for single-valued data members. For both Java and C, the method returns NULL if no value has been set. The function name is always getwidget, where widget is the type of information to be retrieved. In Java, the object is identified by reference. In C, the object name is provided as an argument to the function.

For example, the methods to get the value for the policy name and to get a pointer to an authentication rule object within a policy object called mypolicy are represented this way in Java:

namevar = mypolicy.getName();
  rule1 = mypolicy.getAuthenticationRule();

and in this way in managed C++:

namevar = mypolicy->Name;
rule1 = mypolicy->getAuthenticationRule;

and in this way in C:

const char *namevar;
  amevar = ObAMPolicy_getName(mypolicy);
  ObAMAuthenticationRule_t rule1;
          rule1 = ObAMPolicy_getAuthenticationRule(mypolicy);

5.3.6 Managing Arrays

An object member with multiple elements each having its own value is organized as an array indexed from 0. In order to retrieve information for an element of the array, you need to ask for it based on its position in the array specified as an index.

Objects can contain arrays of either values or other objects. This section describes the following topics, which discuss the kinds of functions you can perform on array members of objects:

• About Keys

• Adding Data to Arrays

• Modifying Data for Objects in Arrays

• Getting a Count of Members in an Array

• Getting Data for Elements of Arrays

• Removing Data from Arrays

5.3.6.1 About Keys

Many objects contain key members. Key members are useful in cases where an object contains an array of member objects. The key enables methods to search for the member object in the array before performing the requested operation.

Note: No set methods are provided for object members which are arrays. Instead, you must replace the old value with a new one. For example, to change the value of an operation in an array of operations for a Policy object (of the policy class), you must remove the old value and add the new value in two steps.

5.3.6.2 Adding Data to Arrays

Objects that contain arrays have methods that allow you to add a new member to the array. If the array is an array of values, then the value is appended to the array and the number of elements in the array increases by one. If the array is an array of objects, then a reference to the new object is added, and the number of elements in the array increases by one. The method name is always addwidget, where widget is the type of information being added. In Java, managed code, and C, the method takes an argument, either the value to be added or the name of the object being added.

For example, given a Policy object called mypolicy, to add another Operation (a string) or to add another resource (an object), the Java code looks like this:

mypolicy.addOperation("GET");
  mypolicy.addResource(myresource);

The managed C++ code looks like this:

mypolicy->AddOperation="GET";
  mypolicy->AddResource=myresource;

The equivalent C code requires an additional argument, the object to which the value or object is being added, and looks like this:

ObAMPolicy_addOperation(mypolicy, "GET");
  ObAMPolicy_addResource( mypolicy, myresource);

5.3.6.3 Modifying Data for Objects in Arrays

Objects can contain arrays of member objects whose values you can modify. You can do this by getting the member from the object, changing its data, and then storing it back in the object. A more facile way to do this is to create an empty member object, fill in the data that needs to be modified, and then use the modify method to overwrite the existing version of the member object in the array of objects.

To modify data for objects in arrays

1. Create an empty member object (of an array of objects), all of whose members will initially be filled with NULL.

2. Set the value for the key member in the empty member object to match the value for the key member in the member object to be overwritten.

   
   

   Note: Refer to the tables for each object type to see which is the key member.

   
   

3. Set values in the members of the member object that you want to change. Leave the values of members that are not to be changed set to NULL.

4. Use the modify method to overwrite the old member object. The function name is always modifywidget, where widget is the type of object being modified. Modify takes one argument, the name of the source member object. Based on the value of the key member, modify locates the matching member object. Where the source member object members are set to NULL, those values in the receiving member object will be unchanged. Where values were specified for members, those values will be changed in the receiving member object.

For example, suppose you want to change the description for a resource whose resource type member is EJB, and the resource is one of the resource members of an array of resource objects for the Policy object mypolicy.

To accomplish this in Java, you would write the following code:

ObAMResource exmplResr = new ObAMResource();
  exmplResr.setResourceType("EJB");
  exmplResr.setDescription(ÒThe New DescriptionÓ);
  mypolicy.modifyResourceType(exmplResr);

To accomplish this in managed C++, you would write the following code:

ObAMResource *exmplResr
            exmplResr = new ObAMResource();
  exmplResr->ResourceType="EJB";
  exmplResr->Description=ÒThe New DescriptionÓ;
  mypolicy->ModifyResourceType=exmplResr;

To do the same in C, you would write the following code:

ObAMResource_t exmplResr;
          exmplResr = ObAMResource_new();
  ObAMResource_setResourceType(exmplResr, "EJB");
  ObAMResource_setDescription (exmplResr,"The New Description");
  ObAMPolicy_modifyResourceType(exmplResr, exmplResr);

5.3.6.4 Getting a Count of Members in an Array

A member with multiple elements each having its own value is organized as an array, indexed from 0. Your application can obtain the value of any element of an array. To do so, you use the get method, which returns the value for the requested element. However, to retrieve information for an element of the array, you need to ask for it by its position in the array.

Before your application calls the get method to get the value of an element of an array, you must know how many members the array contains. You use the getnumberofwidgets method for this purpose, where widget is the type of information the array contains.

The Java version of this method provides the object name by reference, and has no arguments. The C version takes a single argument, the name of the object.

To get the number of resources or the number of operations in a Policy object for a policy domain named mypolicy, example Java code is:

mypolicy.getNumberOfResources();
  mypolicy.getNumberOfOperations();

The equivalent managed C++ code is:

int resNumber = mypolicy->NumberOfResources;
  int operNumber = mypolicy->NumberOfOperations;

The equivalent C code is:

ObAMPolicy_getNumberOfResources(mypolicy);
  ObAMPolicy_getNumberOfOperations(mypolicy);

5.3.6.5 Getting Data for Elements of Arrays

After your application has called the getNumberOfwidgets method to obtain a count of the number of elements of an array, you can get the value of an element of the array. You pass the appropriate get method the index to the element of the array whose value you want returned.

Note: Be careful not to confuse these get methods with the ones used to extract values for single-valued data. You can tell which to use from the member type. If the member type is array, then the get is asking for the value of an element in the array and you must pass the method the index of the element.

The Java methods take one argument, the index. The C functions take the index as the second argument. For C functions, the first argument is the name of the object holding the member from which the data is being retrieved.

For example, from the policy domain called mypolicy, to get the value for one operation in an array of operations or for one policy in an array of policies, the Java code is:

mypolicy.getOperation(myindex); 
  mypolicy.getPolicy(myindex); 

The managed C++ code is:

System::String *operation = mypolicy->getOperation(myindex);
  ObAMPolicyDomainMd *policy = mypolicy->getPolicy(myindex);

The C code looks like this:

ObAMPolicyDomain_getOperation(mypolicy, myindex);
  ObAMPolicyDomain_getPolicy(mypolicy, myindex);

5.3.6.6 Removing Data from Arrays

Objects that contain arrays of values or of member objects have methods that allow you to remove members of the array. To do this, you specify a value to be matched. If the array is an array of values, then the match is done on one of those values. If the array is an array of member objects, then the match is done on the value stored for the key member of the object.

Note: Refer to the tables for each object type to see which is the key member.

Both Java and C take the value to be matched as an argument. For C, this is the second argument; the first is the object from which the value is to be removed.

For example, if you want to remove the operation GET from the Policy mypolicy, the Java code is:

mypolicy.removeOperation("GET");

The managed C++ code is:

mypolicy->removeOperation="GET";

The C code:

ObAMPolicy_removeOperation(mypolicy, "GET");

5.3.7 Using setIDFrom

Every object received from the Access Server contains within its structure a unique identifier, in addition to its name or other key information. Another object of the same type can have its ID set to the same value. A minor change can then be made to the second object, and modify can be used to write just the change back to the original. For simple changes, this is superior to using copy, because no processing time needs to be spent to copy data that will not be changed.

Both Java and C take the name of the object whose ID is to be copied as an argument. For C, this is the second argument; the first is the object whose ID is to be set.

For example, if you want to set the ID for a Policy called workingpolicy to be the same as the ID for an existing Policy called oldpolicy, the Java code is:

workingpolicy.setIDFrom(oldpolicy);

The equivalent managed C++ code is:

workingpolicy->IDFrom=oldpolicy;

The equivalent C code is:

ObAMPolicy_setIDFrom(workingpolicy, oldpolicy);

5.3.8 Using Enumerations

Integer constant values are used to represent sets of predefined valid inputs for certain object members. In this chapter, these are listed as part of the description for the object. For example, the ObAMAction class contains an enumeration with three values:

UNDEFINED = 0;
  FIXEDVALUE = 1;
  ATTRIBUTE = 2;

It is possible for a programmer to pass an incorrect enumerated value to an object within the Policy Manager API. To catch this kind of error, the Java binding checks the enumerated values at run time and throws an ObAMException if an incorrect value is passed.

Managed code uses the ObAmAction_ValueTypeMgd class with the following methods:

isUndefined  isAttribute  isFixedValue  setUndefined

The managed code has wrapped all the needed enums as objects. Each enum has the prerequisite getter and setter methods. For example, the ObAMAction_ValueType enum has been wrapped by the object ObAMAction_ValueTypeMgd class. To create this class and set the value type as FixedValue, you would write the following code:

ObAMAction_ValueTypeMgd valueType = new
  ObAMAction_ValueTypeMgd();
  valueType->setFixedValue();
  if (valueType->isFixedValue == true) {
       <do something here>
  }

The Policy Manager code within the Access Server also checks input enumerated values sent to it for an improperly formatted request. If an error exists, the ObAccessManager method that originated the request receives the error and throws the exception.

5.3.9 ObAccessManager Class

ObAccessManager objects are the main objects used by the Policy Manager API to interact with the Access Server. Each ObAccessManager object represents one or more connections to Access Servers to which requests can be sent to get or set policy or system configuration objects. ObAccessManager objects support methods to perform the following functions:

• Establishment of Policy Manager object(s)

• Connection to the Access Server

• Listing of top level existing objects, by using a special form of get

• Setting of values for new policy domains or changing values for existing policy domains, by using a special form of set

• Testing access to the Access Server

5.3.9.1 Methods to Handle AccessManager Objects

The following methods create a named AccessManager object and define the login information for the user. They are:

• A constructor for the AccessManager Object

  These use the standard constructor syntax described earlier. See "Creating New Objects".

  For Java, to create a new AccessManager object myam, you would write the following code:

  ObAccessManager myam = new ObAccessManager();
  
  

  For managed C++, to create a new AccessManager object myam, you would write the following code:

  ObAccessManagerMgd myam = new ObAccessManagerMgd();
  
  

  For C, to create a new AccessManager object myam, you would write the following code:

  ObAccessManager_t myam;
    myam = ObAccessManager_new();
  
  

• A destructor for the AccessManager Object

  These processes use the standard destructor syntax described earlier. See "Deleting Objects" For Java, the AccessManager objects are removed when they are no longer referenced.

  For managed C++, to remove the AccessManager object called myam, you let it go out of scope. Garbage collection will take care of removing the object.

  For C, to remove the AccessManager object called myam, you would write the following code:

  ObAccessManager_delete(&myam);
  
  

• The setAdmin method

  This method specifies the user ID and password for an administrator for whom requests will be authorized. If the administrator does not exist or the password is not correct, ObAccessManager throws an exception with code ADMIN_LOGIN_FAILED.

  Example code for this in Java is:

  myam.setAdmin("A. Loomis", "ALoomisPassword");
  
  

  Example code for this in managed C++ is:

  myam->setAdmin("A. Loomis", "ALoomisPassword");
  
  

  and in C is:

  ObAccessManager_setadmin_password(myam,ÒA. LoomisÓ,ÒALoomisPasswordÓ);
  
  

• The setCacheUpdates method

  This method sets a Boolean flag to specify whether or not Access Server caches are to be updated for each ObAccessManager set request.

  Example code for this in Java is:

  myam.setCacheUpdates(true);
  
  

  Example code for this in managed C++ is:

  myam->CacheUpdates=true;
  
  

  and example code for this in C is:

  ObAccessManager_setCacheUpdates(myam, 1);
  

5.3.9.2 Connection Methods

The Policy Manager API uses the Access Manager API connection methods from the ObConfig class to establish one or more connections with the Access Server. The following methods are described in more detail in "ObConfig".

• The initialize method

  The initialize method takes an optional argument that specifies the (local) directory path where the Policy Manager API has been installed. If this argument is not given, ObAccessManager will get the directory path from the local environment variable OBACCESSMGR_INSTALL_DIR.

  The initialize method creates a connection to an Access Server specified in the installation configuration file. See the discussion of this file and modifying an AccessGate in the Oracle Access Manager Access Administration Guide. This connection will be maintained until one of the following occurs:

• The shutdown method is called.

• The connection is broken, in which case ObAccessManager will attempt to re-establish the connection to the same or another configured Access Server.

• The configured (API) client session timeout is reached.

  If no connection can be established to any configured Access Server, ObAccessManager will throw an ObAMException with code CANNOT_CONNECT.

Assuming that the local environment variable is set to specify the installation directory location, here is the Java call:

Obconfig.initialize();

For C it is:

Obconfig_initialize(myam);

For managed code, name space for the common classes is:

Oblix::Access::Common

For managed code, the initialize method is a static method of the ObConfigMgd class:

ObConfigMgd.initialize();

• The shutdown method

  The shutdown method closes all connections and deallocates resources used by the Access Client.

  Example coding for this in Java is:

  Obconfig.shutdown();
  
  

  In managed C++ it is:

  ObConfigMgd.shutdown();
  
  

  In C it is:

  Obconfig_shutdown(myam);
  
  

• The getSDKVersion method

  The getSDKVersion method returns the version of the Access Manager SDK under which the Policy Manager API was built.

  To make this call in Java, you would write the following line of code:

  theSDKv = Obconfig.getSDKVersion();
  
  

  To make this call in managed C++, you would write the following line of code:

  string theSDKv = ObConfigMgd.SDKVersion;
  
  

  and to make the call in C:

  char * theSDKv;
    theSDKv = Obconfig_getSDKVersion(myam);
  
  

• The getNAPVersion method

  The getNAPVersion method returns the version of the Oracle Access Protocol used to communicate with Access Servers as defined by the Access Server.

  To make this call in Java, you would write the following line of code:

  theNAPv = Obconfig.getNAPVersion();
  
  

  To make this call in C++, you would write the following line of code:

  theNAPv = Obconfig.NAPVersion;
  
  

  and in C is:

  char * theNAPv;
    theNAPv = Obconfig_getNAPVersion(myam);
  

5.3.9.3 Get Methods

The ObAccessManager get methods return one or more policy domains or configuration objects from the policy directory through the Access Server. The ObAccessManager get methods allow the developer to get information of varying degrees of complexity for the following objects:

• AuthenticationScheme

• AuthorizationScheme

• HostIdentifier

• MasterAuditRule

• PolicyDomains

• ResourceType

• EscapeCharacter

The get methods return an array of objects dependent on the values passed to the method for the following arguments:

• matchName: selects the objects; if NULL, returns all objects.

• matchCriterium: specifies how objects are to be selected by the matchName.

For example, here are the prototypes of the get method for policy domains in the Java and C programming languages.

5.3.9.4 Java

public PolicyDomain[] ObAccessManager.getPolicyDomains( int responselength, String matchName, int matchCriterium)throws ObAMException;

5.3.9.5 C

ObAMArrayOfPolicyDomains_t ObAccessManager_getPolicyDomains(
        ObAccessManager_t am,
        ObAccessManager_ResponseLength responseLength,
        const char *matchName,
        ObAccessManager_MatchCriteria matchCriterium);

The arguments allow the developer to control the precision of the information returned for each object.

• am: For the C programming language, the name of an ObAccessManager object created using the ObAccessManager_new function.

• responseLength: Specifies how much information about the objects is to be returned.

  • There are three levels of increasing response complexity: MIN, MID, and MAX. If responseLength is omitted, the default is MIN.

  • Each get method knows implicitly which data items are to be returned for each level, as indicated by the following table.

  • Placeholders are returned for all possible data in the structure(s) defining the object. For items for which they do not return values, MIN and MID return NULL pointers/references.

    Enumerated values for specifying responseLength are:

    MIN = 0

    MID = 1

    MAX = 2

    Object Type	MIN	MID	MAX
    Authentication Scheme	-Name -Description (In effect, list all Authentication Schemes)	Same as MIN values	-Level -Challenge method -Challenge parameters -SSL required -Challenge redirection -Plug-ins
    Authorization Scheme	-Name -Description (In effect, list all Authorization Schemes)	Same as MIN values	-Shared Library - User parameters -Required parameters -Optional parameters
    EscapeCharacter	(In effect, returns all UTF-8 encoded escape character strings used in an audit rule)	Same as MIN values
    HostIdentifier	-Name -Description (In effect, list all host identifiers)	Same as MIN values	-Hostname variants
    MasterAuditRule	All of the object data; no criteria may be applied	Same as MIN	same as MIN
    PolicyDomain	-Name -Description -Resource types -URL prefixes -Enabled/disabled flag (In effect, show "My Policy Domain")	-Domain names -Policy names -Default rule names -URL prefixes (In effect, show search results for policy domains)	-Complete default rules -Complete policies -Complete admin rules
    ResourceType	-Name -Display Name	Same as MIN values.	-caseSensitive Matching operations

    
    

• matchName: along with matchCriterium, is used to select specific objects for which values are to be returned. The value of matchName is compared to the value of the name member for each candidate object. If matchName is omitted, all objects of the class are retrieved.

• matchCriterium: specifies how object names are to be compared with matchName. The comparison is applied after the matchName has been applied. The choices are as described in the following table. If matchCriterium is omitted, the default is EQUALS = 0 .

  Enumerated values for matchCriterium are:

  EQUALS =0

  CONTAINS = 1

  CONTAINS_IN_ORDER = 2

  BEGINS_WITH =3

  ENDS_WITH =4

  Parameter	Meaning
  EQUALS	The object name matches exactly the value provided.
  CONTAINS	The object name contains the exact string specified. It may be embedded within other characters.
  CONTAINS_IN_ORDER	The object name matches in the string the characters specified, in the specified order, but not necessarily as one contiguous string. For example, "123" would find a match in both "01234" and "102030".
  BEGINS_WITH	The object name begins with the exact value provided, however long it may be.
  ENDS_WITH	The object name ends with the exact value provided, however long it may be.

  
  
  
  

  Note: Security. The getPolicyDomains method returns only those policy domains and policies within domains for which the Policy Manager administrator has at least basic admin rights. All other ObAccessManager get methods require that the admin user be a Master Access Administrator.

  
  

Managed Code Form

For managed code, the get method returns an array of objects for the class the method belongs to.

ArrayList*ObAccessManagerMgd::getPolicyDomains(
       ObAccessManager_ResponseLengthMgd *responseLength,
       System::String *matchName,
       ObAccessManager_MatchCriteriaMgd *matchCriterium);

To set the arguments to the AccessManagerMgd get method, you can use the ObAccessManager_ResponseLengthMgd and the ObAccessManager_MatchCriteriaMgd classes.

Class ObAccessManager_ResponseLengthMgd

To set the responseLength argument for the AccessManagerMgd get method, you can use the ObAccessManager_ResponseLengthMgd class. This class provides a wrapper around the enumeration ObAccessManager_ResponseLength.

The ObAccessManager_ResponseLengthMgd class includes get and set methods. The methods you use to set values are shown here.

ObAccessManager_ResponseLengthMgd();
__property void set_Value(ObAccessManager_ResponseLength value);
void setMin();
void setMid();
void setMax();

where:

setMin() is equivalent to enum value MIN

setMid() is equivalent to enum value MID

setMax() is equivalent to enum value MAX

Class ObAccessManager_MatchCriteriaMgd

To set the MatchCriteria argument for the AccessManagerMgd get method, you can use the ObAccessManager_MatchCriteriaMgd class. This class provides a wrapper around the enumeration ObAccessManager_MatchCriteria.

The ObAccessManager_MatchCriteriaMgd class includes get and set methods. Here are the methods you use to set values:

ObAccessManager_MatchCriteriaMgd();
  __property void set_Value(ObAccessManager_MatchCriteria value);
  void setEquals();
  void setContains();
  void setContainsInOrder();
  void setBeginsWith();
  void setEndsWith();

where:

setEquals() equivalent to enum value EQUALS

setContains() equivalent to enum value CONTAINS

setContainsInOrder() equivalent to enum value CONTAIN_IN_ORDER

setBeginsWith() equivalent to enum value BEGINS_WITH

setEndsWith() equivalent to enum value ENDS_WITH

5.3.9.6 Get Method Examples

To get minimum information for all policy domains whose names contain the string "oblix", you would write the following Java code:

myam.getPolicyDomains(MIN, "oblix", CONTAINS);

For managed C++ code, you would write the following code:

ObAccessManager_ResponseLengthMgd* len = new
  ObAccessManager_ResponseLengthMgd();
  ObAccessManager_MathCriteriaMgd *matchCriterium = new
  ObAccessManager_MatchCriteriaMgd();
  len->setMin();
  matchCriterium->setContains();
  policyDomains =  myam->getPolicyDomains(len, ÒOblixÓ,matchCriterium);

For C, you would write the following code:

ObAccessManager_getPolicyDomains(myam, ObAccessManager_MIN, 
     ÒoblixÓ, ObAccessManager_CONTAINS);

5.3.9.7 Set Method

The API includes one ObAccessManager set method which can be used in the process of creating, modifying, and removing policy domains only. The definition for this method in the Java, Managed Code, and C programming languages is provided in the following sections.

Note: To set values for other high-level objects, you use methods specific to their content. These methods are described in the pertinent sections that follow.

Java

public void setPolicyDomain(ObAMPolicyDomain PDname, int setAction);
     throws ObAMException;

Managed Code

void setPolicyDomain(obAMPolicyDomainMgd 
     *value, ObAccessManager_SetActionMgd *setAction);

C Form

void ObAccessManager_setPolicyDomain(
     ObAccessManager_t accessmanagerObjectName,
     ObAMPolicyDomain_t PDname,
     ObAccessManager_SetAction setAction); 

For the C definition, PDname represents the name of a PolicyDomain. You use the setAction parameter to specify the kind of action to be taken in relation to the specified policy domain object. These are the possible actions:

• Create: A PolicyDomain object is to be created. If objects with the same name already exist, the object will be not be created and the set method returns the error code EXISTING_OBJECT along with the name of the existing object.

• Modify: An existing PolicyDomain object is to be modified. All specified data for the object is modified; undefined data is not affected. If a specified object does not exist, the set method will return the error code NO_OBJECT and the name of the missing object.

• Remove: An existing PolicyDomain object is to be removed. Only the object name is relevant; any data provided along with the object is ignored. If the object does not exist, the set method returns the error code NO_OBJECT and gives the name of the missing object.

  Enumerated values for setAction are:

  CREATE = 0

  MODIFY = 1

  REMOVE = 2

Note: Security. The ObAccessManager administrative user must have basic administration rights for the policy domains in question to be able to call setPolicyDomain. If setPolicyDomain changes the delegate, grant, or basic admin rules of the domain, the administrative user must have delegate or grant rights to do that, as appropriate. If the administrator does not have sufficient rights, the set method returns a NOT_AUTHORIZED error code.

For example, to create a new Policy Domain in Java, you would write the following code:

myam.setPolicyDomain(mypolicy, CREATE);

In managed C++, you would write the following code:

public void setPolicyDomain(ObAmPolicyDomainMgd *pdName,
          ObAccessManager_SetActionMgd *setAction);

using the ObAccessManager_SetActionMgd setCreate method. The ObAccessManager_SetActionMgd class includes the following methods for specifying the action:

void setCreate() = CREATE enum
  void setModify() = MODIFY enum
  void setRemove() = REMOVE enum

and in C you would write the following code:

AccessManager_setPolicyDomain(myam, mypolicy, ObAccessManager_CREATE);

5.3.9.8 Test Access Method

ObAccessManager provides a method to perform an access check, taking as its input an ObAMAccessTest object in which you specify a resource, an optional location, date and time, and a set of users. The testAccess method returns an ObAMAccessTestResults object that includes the applicable policy domain, policies, authorization expression, and determining authorization rules contributing to the outcome of evaluation of the authorization expression. The object also includes information specifying if access by each user is authorized.

Important: If you do not specify explicitly the users who are to be used in the access check test, all of the users in the LDAP directory will included in the test. You may want to perform an access test check using all of the users in the directory. However, if a test of this kind occurs unintentionally because you forgot to specify users, it can incur overhead and consume processing cycles, depending on the size of your LDAP directory.

In C, the caller is responsible for deleting the returned ObAMAccessTestResults object.

Note that this access test is similar but not identical to the ObUserSession.isAuthorized method of the Access Manager API. See "ObUserSession". The differences are:

• testAccess can test access for any user, while isAuthorized can only be used by an authenticated user

• testAccess can test access for any date and time, while isAuthorized always uses the current time.

• testAccess gets its information from the directory; the results are always current. isAuthorized gets its information from the Access Server cache, which may not be current.

The definition (not code example) for this method is:

Java

public ObAMAccessTestManaResults testAccess(ObAMAccessTest testname);

Managed C++ Form

public ObAMAccessTestResultsMgd *getTestAccess(ObAMAccessTestMgd *test);

C Form

ObAMAccessTestResults_t ObAccessManager_testAccess(ObAMAccessTest_t testname);

For example, presuming that the AccessTest object is already built then to do an Access Test in Java, you would write the following code:

myam.testAccess(myaccesstestobject);

In Managed C++, the code is:

myam.gettestAccess(myaccesstestobject);

and in C is:

ObAccessManager_TestAccess(myam, myaccesstestobject);

5.3.10 Access System Configuration Objects

Access System configuration objects represent certain basic object types for which information can be created, modified, deleted, and viewed through the Access System Console GUI. Because they underpin most of the access security supported by the Access System, they cannot be changed using the Policy Manager API. However, these objects are used in creating policy domains and policies. With the exception of managed code supporting classes, you can get but not set values for the following objects included in this group:

• "Class ObAMHostIdentifier"

• "Class ObAMHostIdentifierMgd"

• "Class ObAMResourceType"

• "Class ObAMResourceTypeMgd"

• "Class ObAMAuthenticationScheme"

• "Class ObAMAuthenticationSchemeMgd"

• "Class ObAMAuthenticationScheme_ChallengeMethodMgd"

• "Class ObAMAuthenticationPlugin"

• "Class ObAMAuthenticationPluginMgd"

• "Class ObAMAuthorizationScheme"

• "Class ObAMAuthorizationSchemeMgd"

• "Class ObAMMasterAuditRule"

• "Class ObAMMasterAuditRuleMgd"

5.4 Policy Manager API Classes

This section describes the Policy Manager API classes, including Java and managed code classes. In some cases, the Java class methods are followed by a list of the equivalent C programming language methods.

Also for each Java class, a table is provided showing the data members of the object manipulated by its methods and those of any classes it inherits. Here is how the table is organized:

• Each row of the table begins with the label used to identify the data member.

• The second column indicates the data type, and whether it is a single value or an array.

• The third column describes the range of legal values for the data, enumerated where appropriate

• The last column describes what each data item represents.

Some methods and functions use key data items in order to uniquely identify the object. Where there is only one key data item, that item is indicated as (key). Where two or more data items must be concatenated together to act as a key, they are indicated as (key1), (key2), and so on, in the order of concatenation.

5.4.1 Class ObAMHostIdentifier

Each object of the ObAMHostIdentifier class represents a configured host identifier.

Label	Type	Range	Description
Name (key)	A string Required	Any	The identifying name of the Host Identifier
Description	A string Optional	Any	An optional description
HostName	An array of strings Optional	Any	A set of hostname variations.

5.4.2 Class ObAMHostIdentifierMgd

(Managed Code). Each ObAMHostIdentifier object represents a configured host identifier. For information on the object components, see "Class ObAMHostIdentifier".

Managed Code Form

// getters
__property System::String *get_Name();
__property System::String *get_Description();
__property int get_NumberOfHostnames();
System::String *getHostname(int index);

5.4.3 Class ObAMResourceType

Each object of the ObAMResourceType class represents a built-in or custom resource type.

Label	Type	Range	Description
Name (key)	A string Required	Any	The identifying name of the resource type, which enables its reuse
DisplayName	A string Required	Any	The displayed name
Case- Sensitive Matching	A Boolean flag Required	0, meaning no, or other, meaning yes	A flag indicating whether URL matching for the resource type is case-sensitive
Operations	An array of strings Optional	Any	A set of operations defined for the resource type

Java

public String getName();
  public String getDisplayName();
  public boolean getCaseSensitiveMatching();
  public int getNumberOfOperations();
  public String getOperation(int index);

5.4.4 Class ObAMResourceTypeMgd

(Managed Code). Each object of the ObAMResourceType class represents a built-in or custom resource type.

Label	Type	Range	Description
Name (key)	A string Required	Any	The identifying name of the resource type, which enables its reuse
DisplayName	A string Required	Any	The displayed name
Case- Sensitive Matching	A Boolean flag Required	True, false	A flag indicating whether URL matching for the resource type is case-sensitive
Operations	An array of strings Optional	Any	A set of operations defined for the resource type

Managed Code Form

// getters
__property System::String *get_Name();
__property System::String *get_DisplayName();
__property bool get_CaseSensitiveMatching();
__property int get_NumberOfOperations();
System::String *getOperation(int index);

5.4.5 Class ObAMAuthenticationScheme

Each object of the ObAMAuthenticationScheme class represents a configured authentication scheme. Every authentication rule must contain the name of an existing authentication scheme.

Label	Type	Range	Description
Name (key)	A string (Required)	Any	The identifying name of the Authentication Scheme
Description	A string (Optional)	Any	An optional description
Level	Numeric (Required)	Any	A level ranking the security of the scheme relative to other configured schemes
Challenge Method	A member of the enumerated list (Required)	Any item in the following enumerated list: UNDEFINED=0 NONE=1 BASIC=2 X509=3 FORM=4 EXTERNAL=5	The method to be used to challenge the user for credentials.
Challenge Parameters	An array of strings (Required)	Any	A set of parameters to be used in the challenge
SSLrequired	A Boolean flag (Required_	0, meaning no, or other, meaning yes	A flag indicating whether an SSL security connection is required for the challenge
Plugin	An array of authentication plugin objects (Optional)	See the class definition	An array of plug-ins to process the credentials to produce the authenticated user
Enabled	A boolean flag		A flag to enable and disable the authentication scheme

Java

public String getName();
  public String getDescription(); 
  public int getLevel(); 
  public int getChallengeMethod(); 
  public boolean getSSLrequired(); 
  public int getNumberOfChallengeParameters(); 
  public String getChallengeParameter(int index);
  public int getNumberOfPlugins(); 
  public ObAMAuthenticationPlugin getPlugin(int index);
  public boolean getEnabled();

5.4.6 Class ObAMAuthenticationSchemeMgd

(Managed Code). Each object of the ObAMAuthenticationSchemeMgd class represents a configured authentication scheme. See "Class ObAMAuthenticationScheme" for details on the components of this object.

// getters
__property System::String *get_Name();
__property System::String *get_Description();

5.4.7 Class ObAMAuthenticationScheme_ChallengeMethodMgd

(Managed Code). This is a Managed Value Type class which defines the value types used by the ObAMAuthenticationSchemeMgd class. This class provides a wrapper around the enum ObAMAuthenticationScheme_ChallengeMethod. You can set the value using the setter methods, or you can use an ObAMAuthenticationScheme_ChallengeMethod value.

__property int get_Level();
  __property ObAMAuthenticationScheme_ChallengeMethodMgd *get_ChallengeMethod();
  __property bool get_SSLrequired();
  __property bool get_Enabled(); 
  __property System::String *get_ChallengeRedirectURL();
  __property int get_NumberOfChallengeParameters();
  __property int get_NumberOfPlugins();
  System::String *getChallengeParameter(int index);
  ObAMAuthenticationPluginMgd *getPlugin(int index);

// Get and set values
__property bool get_isUndefined();
__property bool get_isNone();
__property bool get_isBasic();
__property bool get_isX509();
__property bool get_isForm();
__property bool get_isExt();
__property ObAMAuthenticationScheme_ChallengeMethod get_Value();
__property void 
set_Value(ObAMAuthenticationScheme_ChallengeMethod value);
void setUndefined();
void setNone();
void setBasic();
void setX509();
void setForm();
void setExt();

For managed code, the mapping between the enumerated list (the challenge method) and the managed code class is as follows:

ObAMAuthenticationScheme_ChallengeMethod:
setUndefined() = UNDEFINED
setNone() = NONE
setBasic() = BASIC
setX509 = X509
setForm() = FORM
setExt() = EXT

5.4.8 Class ObAMAuthenticationPlugin

Each object of the ObAMAuthenticationPlugin class represents an authentication plug-in that can be configured into an authentication scheme.

Label	Type	Range	Description
Order	An integer Required	Any	The order in which the plug-in is executed in the authentication scheme
Name (key)	A string Required	Any	The name of the plug-in (without the file extension), which is either a built-in plug-in name or the name of the custom plug-in library
Parameters	A string Optional	Any	A single string, of user defined parameters for the plug-in

Java

public int getOrder(); 
  public String getName(); 
  public String getParameter();

5.4.9 Class ObAMAuthenticationPluginMgd

(Managed Code). Each ObAMAuthenticationPlugin represents an Authentication Plug-in that can be configured into an authentication scheme. For details on the object components, see "Class ObAMAuthenticationPlugin".

Managed Code Form

// getters 
__property int get_Order();
__property System::String *get_Name();
__property System::String *get_Parameters(); 

5.4.10 Class ObAMAuthorizationScheme

Each object of the ObAMAuthorizationScheme class represents a custom authorization scheme.

Label	Type	Range	Description
Name (key)	A string Required	Any	The identifying name of the Authorization Scheme
Description	A string Optional	Any	A description to displayed for the scheme
Library	A string Required	Any	The name of the library file implementing the scheme
User Parameters	An array of strings Optional	Any	Parameters defined by the user
Required Parameters	An array of Parameter objects Optional	See the class definition	Parameters built into the scheme and required for its correct operation, if any
Optional Parameters	An array of Parameter objects Optional	See the class definition.	Parameters with which the scheme will work, if they are provided

Java

public String getDescription(); 
  public String getLibrary(); 
  public int getNumberOfUserParameters();
  public int getNumberOfRequiredParameters();
  public int getNumberOfOptionalParameters();
  public String getUserParameter(int index);
  public ObAMParameter getRequiredParameter(int index);
  public ObAMParameter getOptionalParameter(int index);

5.4.11 Class ObAMAuthorizationSchemeMgd

(Managed Code). Each ObAMAuthorizationSchemeMgd represents a custom authorization scheme. For details on components of this object, see "Class ObAMAuthorizationScheme".

Managed Code Form

// getters 
__property System::String *get_Name();
__property System::String *get_Description();
__property System::String *get_Library();
__property int get_NumberOfUserParameters();
__property int get_NumberOfRequiredParameters();
__property int get_NumberOfOptionalParameters();
System::String *getUserParameter(int index);
ObAMParameterMgd *getRequiredParameter(int index);
ObAMParameterMgd *getOptionalParameter(int index);

Java

public String getName(); 
  public String getDescription(); 
  public int getNumberOfHostnames(); 
  public String getHostname(int index); 

5.4.12 Class ObAMMasterAuditRule

A object of the ObAMMasterAuditRule class represents the master audit rule, which specifies global audit parameters and defaults to be used if there is no audit rule specified for a specific policy.

In 10g (10.1.4.0.1):

• In the C language API, the ObAMMasterAuditRule_getEscapeCharacter remains and you may continue using this. However, the audit escape character must be an ASCII character; otherwise the return value is incorrect. In this case, you must modify your C code to use the new API.

• On Java clients, the ObAMMasterAuditRule_getEscapeCharacter works correctly and you can continue using this even when the audit escape character is not an ASCII character.

• In the C language API, a new ObAMMasterAuditRule_getUTF8EscapeCharacter has been added, which returns a pointer to the UTF-8 encoded audit escape character.

Label	Type	Range	Description
DateFormat	Enum Required	An integer from the following enumerated set of possible date formats: UNDEFINED=0 INTEGER = 1 MMDDYYYY=2 DDMMYYYY=3 ISO8601 = 4 YYYYMMDD=5 YYYYDDMM=6	The format to be used for the date in each audit record
Escape Character	A string Required	Any	The escape character to be used in audit records Note: See behavior details in the list preceding this table for details.
RecordFormat	A string Required	Any	The format for the audit record
EventMapping	An array of strings associated with event types	Any	The mapping of audit events to character strings to be used in the audit record

Java

public int getDateFormat(); 
  public char getEscapeCharacter(); 
  public String getRecordFormat(); 
  public String getEventMapping(int eventType);

The get method used to work with event mapping in the Master Audit Rule is unusual. The array of EventMapping strings consists of a series of pairs of data. Each pair is the association of a character string with an event type. The event type is provided as an enumerated argument to the getEventMapping method to return the character string associated with it.

The enumerated values for eventtype are the following:

AUTHENTICATION_FAILURE = 0
  AUTHENTICATION_SUCCESS = 1
  AUTHORIZATION_FAILURE = 2
  AUTHORIZATION_SUCCESS= 3

5.4.13 Class ObAMMasterAuditRuleMgd

(Managed Code) An ObAMMasterAuditRule object represents the master audit rule, which specifies global audit parameters and defaults to be used if there is no audit rule specified for a specific policy.

Label	Type	Range	Description
DateFormat	Enum Required	An integer from the following enumerated set of possible date formats: UNDEFINED=0 INTEGER = 1 MMDDYYYY=2 DDMMYYYY=3 ISO8601 = 4 YYYYMMDD=5 YYYYDDMM=6	The format to be used for the date in each audit record
Escape Character	A string Required	Any	The escape character to be used in audit records
RecordFormat	A string Required	Any	The format for the audit record
EventMapping	An array of strings associated with event types	Any	The mapping of audit events to character strings to be used in the audit record

Managed Code Form

// getters
  System::String *getEventMapping(ObAMAuditRule_EventTypeMgd *eventType);
  __property ObAMMasterAuditRule_DateFormat get_DateFormat();
  __property const char get_EscapeCharacter();
  __property System::String *get_RecordFormat();

5.4.14 Access Policy Objects

Access policy objects represent certain basic object types for which information can be created, modified, deleted, and read through the Policy Manager GUI.

From the perspective of a policy domain, there are several tiers of objects in which the higher-level objects include objects subordinate to them. This perspective is not a true one in that policies which a policy domain contains can include their own rules and expressions containing access conditions and actions. However, taking policies into account, from a hierarchical perspective, the objects are:

Level 1: "Class ObAMPolicyDomain"

Level 2: "Class ObAMAdminRule"

Level 3: "Class ObAMAuthorizationExpr"

Level 4: "Class ObAMAuthorizationRule"

Level 5: "Class ObAMAuthenticationRule" and "Class ObAMAuthorizationRule"

Level 6: "Class ObAMAccessConditionsMgd" and "Class ObAMTimingConditions"

Level 7: "Class ObAMAction", "Class ObAMAuditRule", "Class ObAMDate", "Class ObAMIdentity", "Class ObAMParameter", "Class ObAMTime"

Level 8: "Class ObAMPolicy"

Description of these classes follows the form that is used for the"Access System Configuration Objects".

Definitions for the enumerated values and methods of these classes are given in Appendix B, "Policy Manager API Definitions".

5.4.14.1 About String Names

Many objects contain a name data member whose value you specify as a string, and a method to set that value, as shown in the following method definition:

public void setName(String value);

To refer to the object elsewhere, for example, passing it as a parameter to a method of another class, you must specify exactly the string that you gave for that name when you created the object.

For example, if you created an authorization rule called "Authz Rule 1" as is done in the following snippet of code,

ObAMAuthorizationRule authzRule1 = new
  ObAMAuthorizationRule();
  authzRule1.setName("Authz Rule 1");
  authzRule1.setEnabled(true);

and then you created another authorization rule called "Authz Rule 2", you could use those rules in an authorization expression.

To create an authorization expression containing the two rules, you would refer to each one of them by the exact string given as its name, as shown in the following line of code:

p1_authzExpr.setExpression("Authz Rule 1 & Authz Rule 2");

This concept applies to all objects having a name data member.

5.4.15 Class ObAMPolicyDomain

An object of the ObAMPolicyDomain class represents an access policy domain that includes a set of resources and the authentication rule and authorization expression that control access to those resources. Optionally, a policy domain can contain audit rules. A policy domain also specifies the administrators who can manage the domain. For details about policy domains and protecting resources with policy domains, see the Oracle Access Manager Access Administration Guide.

A policy domain can also include one or more policies, each of which can have its own rules and authorization expression. For information, see "Class ObAMPolicy".

Adding Objects to a Policy Domain: When you add to a policy domain a previously created object containing a named data member, you must refer to the object by the exact string given as the name when you created the object. For details, see "About String Names".

Label	Type	Range	Description
Name (key)	A string Required	Any	A unique name
Description	A string Optional	Any	The displayed description for the Policy Domain
Enabled	A Boolean flag, Optional	0, meaning no, or other, meaning yes.	A flag indicating if the Policy Domain is enabled
Resource	An array of resource objects Optional	See the class definition .	A set of resources with resource types, host IDs, and URL prefixes that identify the world to which the policy domain applies
Default Authentication Rule	One Authentication Rule object Optional	See the class definition.	An authentication rule that specifies, among other things, the challenge method to be used to obtain credentials from the user.
Default Authorization Expression	One Authorization Expression object for a policy domain	See the class definition .	An authorization expression contains one or more authorization rules whose collective evaluation determines if the requesting user is granted access to the resource The authorization rules of an expression must be specified as strings matching exactly the names of the rules given when they were created. For details, see "Class ObAMAuthorizationRule" and "Class ObAMAuthorizationExpr". Rules of an authorization expression are evaluated based on precedence and priority. See details about valuation of the rules of an expression in the Oracle Access Manager Access Administration Guide.
Authorization Rule	One or more Authorization Rule objects for a policy domain	See the class definition .	A rule specifying who is allowed or not allowed to use a protected resource and under what conditions. Authorization Rules are included in Authorization Expressions. To specify an authorization rule in an authorization expression, the string given as its name must be specified exactly. Authorization Rules created for a policy domain can be used for the policy domain or any of its policies.
Default AuditRule	One Audit Rule object Optional	See the class definition.	An audit rule that is used if no policy-specific audit rule applies
Policy	An array of Policy objects Optional	See the class definition .	A policy that further qualifies access requirements for the set of resources it applies to.
Delegate AdminRule	One AdminRule object Optional	See the class definition.	An admin rule that specifies who is allowed to delegate administration rights for this policy domain, including the right to further delegate rights
Grant AdminRule	One AdminRule object Optional	See the class definition .	An admin rule that specifies who is allowed to grant basic rights for this Policy Domain to other users
Basic AdminRule	One AdminRule object Optional	See the class definition on	An admin rule that specifies who is allowed basic rights to manage this Policy Domain

Java

public String getName();
  public String getDescription(); 
  public boolean getEnabled();
  public int getEnabled();
  public int getNumberOfResources();
  public ObAMResource getResource(int index); 
  public ObAMAuthenticationRule getDefaultAuthenticationRule(int index);
  public int getNumberOfPolicies(); 
  public OAMPolicy getPolicy(int index); 
  public int getNumberOfAuthorizationRules();
  public ObAMAuthorizationRule getAuthorizationRule(int index);
  public ObAMAuthorizationExpr getDefaultAuthorizationExpr();
  public ObAMAuditRule getDefaultAuditRule(); 
  public ObAMAdminRule getDelegateAdminRule(); 
  public ObAMAdminRule getGrantAdminRule(); 
  public ObAMAdminRule getBasicAdminRule();
  public void modifyAuthorizationRule(ObAMAuthorizationRule value);
  public void modifyPolicy(ObAMPolicy value);
  public void modifyResource(ObAMResource value);
  public void setDescription(String value); 
  public void setName(String value); 
  public void setEnabled(boolean value); 
  public void setDefaultAuthenticationRule(ObAMAuthenticationRule value);
  public void setDefaultAuthorizationExpr(ObAMAuthorizationExpr value);
  public void setDefaultAuditRule(ObAMAuditRule value); 
  public void setDelegateAdminRule(ObAMAdminRule value); 
  public void setGrantAdminRule(ObAMAdminRule value); 
  public void setIDFrom(ObAMPolicyDomain other);
  public void setBasicAdminRule(ObAMAdminRule value); 
  public void addResource(ObAMResource value); 
  public void addAuthorizationRule(ObAMAuthorizationRule value);
  public void addPolicy(ObAMPolicy value); 
  public void removeResource(ObAMResource value);
  public void removeAuthorizationRule(ObAMAuthorizationRule value);
  public void removePolicy(ObAMPolicy value);

Creating a Policy Domain

Example 5-1 shows an excerpt from an example program that creates a policy domain called My Domain to protect certain resources, and then it enables the domain.

The code that would call the rest of the methods necessary to define a policy domain, methods to set the default authentication rule, add authorization rules to the policy domain, set the default authorization expression, and so forth, is not shown here. Those ObAMPolicyDomain methods and others add objects to the policy domain, and they are called only after the objects are created.

The code excerpt in Example 5-1 performs the following functions:

• It creates a new policy domain object (domain), and it sets the name of the policy domain to My Domain.

  ObAMPolicyDomain domain = new ObAMPolicyDomain();
    domain.setName("My Domain");
  
  

• It sets a description for the policy domain

  domain.setDescription("This domain was created by the 
             ObAM example program.");
  

• It enables the policy domain. (You must enable a policy domain before you can use it.)

  domain.setEnabled(true);
  
  

• It creates an ObAMResource object called resource and sets the resource type to http.

  ObAMResource resource = new ObAMResource();
    resource.setResourceType("http");
  
  

• Using the new resource object, it specifies the location of the resources to be included in the policy domain. It sets the host ID and it sets the URL prefix.

  Together with the host ID, the URL defines the path for the resources protected by the policy domain (http://host1/myresources).

  All resources added to a policy domain are identified by the host ID for the host on which they reside and their URLs.

  resource.setHostID("host1");
    resource.setURLPrefix("/myresources");
  
  

• It adds the resources to the policy domain

  domain.addResource(resource);
  

Example 5-1 Creating a Policy Domain

.
                  .
                  .                     
  ObAMPolicyDomain domain = new ObAMPolicyDomain();
  domain.setName("My Domain");
  domain.setDescription("This domain was created by the ObAM example program.");
  domain.setEnabled(true);
  ObAMResource resource = new ObAMResource();
  resource.setResourceType("http");
  resource.setHostID("host1");
  resource.setURLPrefix("/myresources");
  domain.addResource(resource);
                  .
                  .
                  .                     

5.4.16 Class ObAMPolicyDomainMgd

(Managed Code) An object of the ObAMPolicyDomainMgd class represents an access policy domain that determines if access to a set of resources is authorized for a set of users meeting certain conditions. A Policy Domain contains default rules and it can contain policies that further qualify access requirements for subsets of resources. A policy domain also specifies the administrators who can manage the domain. For details on the object class components, see "Class ObAMPolicyDomain".

Managed Code Form

// Getters and setters
__property System::String *get_Name();
__property System::String *get_Description();
__property bool get_Enabled();
__property int get_NumberOfResources();
__property int get_NumberOfAuthorizationRules();
__property int get_NumberOfPolicies();
ObAMResourceMgd *getResource(int index);
ObAMAuthorizationRuleMgd *getAuthorizationRule(int index);
__property ObAMAuthorizationExprMgd *get_DefaultAuthorizationExpr();
ObAMPolicyMgd *getPolicy(int index);
__property ObAMAuthenticationRuleMgd *get_DefaultAuthenticationRule();
__property ObAMAuditRuleMgd *get_DefaultAuditRule();
__property ObAMAdminRuleMgd *get_DelegateAdminRule();
__property ObAMAdminRuleMgd *get_GrantAdminRule();
__property ObAMAdminRuleMgd *get_BasicAdminRule(); 
__property void set_IDFrom(ObAMPolicyDomainMgd *other);
__property void set_Name(System::String *value);
__property void set_Description(System::String *value);
__property void set_Enabled(bool value);
__property void set_DefaultAuthenticationRule(ObAMAuthenticationRuleMgd *value);
__property void set_DefaultAuthorizationExpr(ObAMAuthorizationExprMgd *expr);
__property void set_DefaultAuditRule(ObAMAuditRuleMgd *value);
__property void set_DelegateAdminRule(ObAMAdminRuleMgd *value);
__property void set_GrantAdminRule(ObAMAdminRuleMgd *value);
__property void set_BasicAdminRule(ObAMAdminRuleMgd *value);
__property void set_AddResource(ObAMResourceMgd *value);
__property void set_AddAuthorizationRule(ObAMAuthorizationRuleMgd *value);
__property void set_AddPolicy(ObAMPolicyMgd *value);
__property void set_ModifyResource(ObAMResourceMgd *value);
__property void set_ModifyPolicy(ObAMPolicyMgd *value);
__property void set_ModifyAuthorizationRule(ObAMAuthorizationRuleMgd *value);
__property void set_RemoveResource(ObAMResourceMgd *value);
__property void set_RemoveAuthorizationRule(ObAMAuthorizationRuleMgd *value);
__property void set_RemovePolicy(ObAMPolicyMgd *value);             

5.4.17 Class ObAMAdminRule

An object of the ObAMAdminRule class specifies users who are authorized to administer a policy domain.

Label	Type	Range	Description
Role (no key)	An array of strings. At least one required.	One of: none anyone noone	A set of roles. NOTE: The array format here allows for future use. Currently, the "array" is limited to one value.
Person	An array of Identity objects. Optional, but at least one of Person, Group, or Rule is required.	See the class definition.	A set of people.
Group	An array of Identity objects. Optional, but at least one of Person, Group, or Rule is required.	See the class definition.	A set of named groups (of people).
Rule	An array of strings. Optional, but at least one of Person, Group, or Rule is required.	Any	A set of LDAP rules that select user profiles.

Java

public int getNumberOfPersons(); 
  public int getNumberOfGroups(); 
  public int getNumberOfRoles(); 
  public int getNumberOfRules(); 
  public ObAMIdentity getPerson(int index); 
  public ObAMIdentity getGroup(int index); 
  public String getRole(int index); 
  public String getRule(int index); 
  public void addRole(String value); 
  public void addPerson(ObAMIdentity value); 
  public void addGroup(ObAMIdentity value); 
  public void addRule(String value) 
  public void removeRole(String value); 
  public void removePerson(ObAMIdentity value); 
  public void removeGroup(ObAMIdentity value); 
  public void removeRule(String value);
  public void setIDFrom(ObAMAdminRule other);

5.4.18 Creating an Administrator Rule

The code in Example 5-2 performs the following functions:

• It creates an administrator rule object (ObAMAdminRule) to be used to assign to someone Delegated Administrator rights and responsibilities for the policy domain called My Domain.

  ObAMAdminRule adminRule = new ObAMAdminRule();
  
  

  This listing presupposes that the policy domain was created previously and called My Domain.

• It creates an identity object (ObAMIdentity) called adminPerson to be used to identify the person to be assigned administrative rights for the domain.

  ObAMIdentity adminPerson = new ObAMIdentity();
  
  

• Using the methods of the ObAMIdentity class, it sets the login ID for the person designated administrator of the policy domain.

  adminPerson.setLoginID("A.Loomis");
  
  

• Then it adds the ObAMIdentity object called adminPerson to the administrator rule created at the outset of the code excerpt.

  adminRule.addPerson(adminPerson);
  
  

• Finally, it calls the ObAMPolicyDomain's setDelegateAdminRule method to add the adminRule rule to the policy domain called My Domain.

  domain.setDelegateAdminRule(adminRule);
  

Example 5-2 Assigning Administrator Rights

.
                  .
                  .
  ObAMAdminRule adminRule = new ObAMAdminRule();
  ObAMIdentity adminPerson = new ObAMIdentity();
  adminPerson.setLoginID("A.Loomis");
  adminRule.addPerson(adminPerson);
  domain.setDelegateAdminRule(adminRule);
                  .
                  .
                  .

5.4.19 Class ObAMAdminRuleMgd

(Managed Code). An object of the ObAMAdminRule class specifies users who are authorized to administer a policy domain. For details on the object class components, see "Class ObAMAdminRule".

Managed Code Form

// Getters and setters
__property int get_NumberOfPersons();
__property int get_NumberOfGroups();
__property int get_NumberOfRoles();
__property int get_NumberOfRules();
ObAMIdentityMgd *getPerson(int index);
ObAMIdentityMgd *getGroup(int index);
System::String *getRole(int index);
System::String *getRule(int index);
__property void set_IDFrom(ObAMAdminRuleMgd *other);
__property void set_AddRole(System::String *value);
__property void set_AddPerson(ObAMIdentityMgd *person);
__property void set_AddGroup(ObAMIdentityMgd *group);
__property void set_AddRule(System::String *value);
__property void set_RemoveRole(System::String *value);
__property void set_RemovePerson(ObAMIdentityMgd *person);
__property void set_RemoveGroup(ObAMIdentityMgd *group);
__property void set_RemoveRule(System::String *value);

5.4.20 Class ObAMPolicy

An object of the ObAMPolicy class represents an access policy within a policy domain. The policy determines who can access a set of resources within the policy domain protected by the policy. It specifies the users allowed or denied access and the conditions controlling access. If any of the Authentication or Audit rules or the Authorization Expression in the policy are omitted, the corresponding default rule or expression for the policy domain that includes the policy is used. For background information about policies nd policy domains, see the Oracle Access Manager Access Administration Guide.

Adding Objects to a Policy: When you add to a policy a previously created object containing a named data member, you must refer to the object by the exact string given as the name when you created the object. For example, you must specify the names of authorization rules as strings matching exactly the names that were given when the authorization rules were created and added to the policy domain. For details, see "About String Names".

Label	Type	Range	Description
Name (key)	A string Required	Any	A unique name
Description	A string Optional	Any	A description
ResourceType	A string Optional	Any	The resource type for the set of resources to which the policy applies
Operations	An array of strings Required	Any	A set of access operations (defined for the resource type) to which the policy applies.
HostID	A string Optional	Any	A host ID for the set of resources.
Resources	An array of Resource objects Required	See the class definition.	A set of resources that further qualify the set of resources.
URLPattern	A string Optional	Any	A URL pattern that further qualifies the set of resources.
QueryString	A string Optional	Any	A query string to be matched against request data.
Parameters	A array of Parameter objects Optional	See the class definition.	A set of parameters to be matched against request data.
AuthenticationRule	One Authentication Rule object Optional	See the class definition.	An authentication rule includes an authentication scheme, which among other things, specifies the challenge method used to obtain credentials from the user. You must specify an authentication scheme that has already been created.
Authorization Expression	One Authorization Expression for each policy Optional	See the class definition.	An authorization expression contains one or more authorization rules whose evaluation determines if the user requesting the resource is granted access to it. The authorization rules of an expression must be specified as strings matching exactly the names of the rules given when they were created. If a policy does not include an authorization expression, the expression for the policy domain applies. For details, see "Class ObAMAuthorizationRule" and "Class ObAMAuthorizationExpr". Rules of an authorization expression are evaluated based on precedence and priority. See details about evaluation of the rules of an expression and configuring user authorization in the Oracle Access Manager Access Administration Guide.
AuditRule	One AuditRule object Optional	See the class definition.	An audit rule that specifies how the access is to be audited.

Java

public String getName(); 
  public String getDescription(); 
  public String getResourceType(); 
  public String getHostID(); 
  public String getURLPattern(); 
  public String getQueryString(); 
  public int getNumberOfOperations(); 
  public int getNumberOfResources(); 
  public int getNumberOfParameters(); 
  public ObAMAuthorizationExpr getAuthorizationExpr();
  public ObAMAuthenticationRule getAuthenticationRule();
  public String getOperation(int index); 
  public ObAMResource getResource(int index); 
  public ObAMParameter getParameter(int index); 
  public ObAMAuditRule getAuditRule(); 
  public void setName(String value); 
  public void setDescription(String value); 
  public void setResourceType(String value); 
  public void setHostID(String value); 
  public void setURLPattern(String value); 
  public void setQueryString(String value); 
  public void setAuthorizationExpr(ObAMAuthorizationExpr value);
  public void setAuthenticationRule(ObAMAuthenticationRule value);
  public void setAuditRule(ObAMAuditRule value);
  public void setIDFrom(ObAMPolicy other);
  public void addOperation(String value); 
  public void addResource(ObAMResource value); 
  public void addParameter(ObAMParameter value); 
  public void removeOperation(String value); 
  public void removeResource(ObAMResource value); 
  public void removeParameter(ObAMParameter value); 
  public void modifyParameter(ObAMParameter value); 
  public void modifyResource(ObAMResource value);

Creating a Policy

The code in Example 5-3 creates a policy called My Domain Policy 1. The policy protects a resource within the policy domain called My Domain. My Domain was created previously by the application this code was excerpted from.

The code in this listing sets an authorization expression for the policy domain. An authorization expression includes authorization rules, which together are used to control access to resources of the policy domain.

The code performs the following functions:

• It creates a policy object called policy1 for the new policy, and it sets the name of the policy to My Domain Policy 1.

  ObAMPolicy policy1 = new ObAMPolicy();
    policy1.setName("My Domain Policy 1");
  
  

• It specifies the type of resource the policy applies to, and it identifies the resource by giving its host ID and URL.

  policy1.setResourceType("http");        
    policy1.setHostID("host1");
    policy1.setURLPattern("/myresources/doc1.html");
  
  

• It defines for the My Domain Policy 1 policy the kinds of operations that can be performed on the protected http resource. The GET and POST operations are allowed.

  policy1.addOperation("GET");
    policy1.addOperation("POST");
  
  

• It adds the resource to the My Domain Policy 1 policy.

  policy1.addResource(resource);
  
  

• It creates an ObAMAuthorizationExpr object called p1_authzExpr to be used for the My Domain Policy 1 policy's authorization protection.

  ObAMAuthorizationExpr p1_authzExpr = new;
  ObAMAuthorizationExpr();
  
  

• It defines the authorization expression for the p1_authzExpr object. The expression consists of authorization rule 1 (Authz Rule 1) and authorization rule 2 (Authz Rule 2). These are the names of the rules given as unique strings when the rules were created. To identify the rules of an expression, you must specify exactly the strings given as their names. For details, see "Class ObAMAuthorizationRule" and "Class ObAMAuthorizationExpr".

  p1_authzExpr.setExpression("Authz Rule 1 & Authz Rule 2");
  
  

  For details about how authorization expressions are evaluated see details about authorization expression evaluation and configuring user authorization in the Oracle Access Manager Access Administration Guide.

• It sets the duplicate actions policy for the p1_authzExpr authorization expression, and then it adds the authorization expression to the My Domain Policy 1 policy.

  p1_authzExpr.setDuplicateActionsPolicy(ObAMAuthorizationExpr.UNDEFINED);
    policy1.setAuthorizationExpr(p1_authzExpr);
  
  

  The duplicate actions policy for My Domain Policy 1 takes precedence over the one set for the default authorization expression for the policy domain My Domain.

  For information explaining what duplicate actions are and how they are handled for a policy based on your specification, see "Class ObAMAuthorizationExpr". Also, see details about Duplicate actions and configuring user authorization in the Oracle Access Manager Access Administration Guide.

• Finally, it adds the My Domain Policy 1 policy to the My Domain domain.

  domain.addPolicy(policy1);
  
  

Example 5-3 Creating Policies Within the My Domain Policy Domain

.
                  .
                  .
  ObAMPolicy policy1 = new ObAMPolicy();
  policy1.setName("My Domain Policy 1");
  policy1.setResourceType("http");
  policy1.setHostID("host1");
  policy1.setURLPattern("/myresources/doc1.html");
  policy1.addOperation("GET");
  policy1.addOperation("POST");
  policy1.addResource(resource);
  ObAMAuthorizationExpr p1_authzExpr = new ObAMAuthorizationExpr();
  p1_authzExpr.setExpression("Authz Rule 1 & Authz Rule 2");
  p1_authzExpr.setDuplicateActionsPolicy(ObAMAuthorizationExpr.UNDEFINED);
  policy1.setAuthorizationExpr(p1_authzExpr);
  domain.addPolicy(policy1);

5.4.21 Class ObAMPolicyMgd

(Managed Code). An ObAMPolicyMgd object represents an access policy that determines if access to a set of resources is authorized for a set of users meeting certain conditions. If any of the Authentication or Audit rules or the Authorization Expression are omitted, the corresponding rule in the policy domain that contains the policy will be used. For details on the object class components, see "Class ObAMPolicy".

Managed Code Form

// Getters and setters
__property System::String *get_Name();
__property System::String *get_Description();
__property System::String *get_ResourceType();
__property System::String *get_HostID();
__property System::String *get_URLPattern();
__property System::String *get_QueryString();
__property int get_NumberOfOperations();
__property int get_NumberOfResources();
__property int get_NumberOfParameters();
System::String *getOperation(int index);
ObAMResourceMgd *getResource(int index);
ObAMParameterMgd *getParameter(int index);
__property ObAMAuthorizationExprMgd *get_AuthorizationExpr();
__property ObAMAuthenticationRuleMgd *get_AuthenticationRule();
__property ObAMAuditRuleMgd *get_AuditRule();
__property void set_IDFrom(ObAMPolicyMgd *other);
__property void set_Name(System::String *value);
__property void set_Description(System::String *value);
__property void set_ResourceType(System::String *value);
__property void set_HostID(System::String *value);
__property void set_URLPattern(System::String *value);
__property void set_QueryString(System::String *value);
__property void set_AuthenticationRule(ObAMAuthenticationRuleMgd *rule);
__property void set_AuthorizationExpr(ObAMAuthorizationExprMgd *expr);
__property void set_AuditRule(ObAMAuditRuleMgd *rule);
__property void set_AddOperation(System::String *value);
__property void set_AddResource(ObAMResourceMgd *resource);
__property void set_AddParameter(ObAMParameterMgd *parameter);
__property void set_ModifyResource(ObAMResourceMgd *resource);
__property void set_RemoveOperation(System::String *value);
__property void set_RemoveResource(ObAMResourceMgd *resource);
__property void set_RemoveParameter(ObAMParameterMgd *parameter);

5.4.22 Class ObAMAuthenticationRule

An object of the ObAMAuthenticationRule class specifies how authentication is to be performed when users request access to resources protected by the rule. Every policy domain must include one and only one default authentication rule containing an ObAMAuthenticationScheme object. Optionally, each policy a policy domain contains can include its own authentication rule. If it does not include one, the policy is protected by the policy domain's authentication rule.

Authentication Schemes: An authentication rule must contain an authentication scheme, which specifies, among other information, the challenge method used to obtain the user's credentials and authenticate the user. You can use a predefined authentication scheme, or you can use a custom one. In any case, you must specify an authentication scheme that has already been created. To get a list of existing authentication schemes, you must use the Access System Console. See details about configuring user authentication in the Oracle Access Manager Access Administration Guide.

Actions for Authentication Rule Objects: For an authentication rule object, you can set the kinds of actions to be taken if authentication of the user is successful. You can also set the kinds of actions to be taken if user authentication fails.

When you create it, the ObAMAuthenticationRule class inherits the ObAMObjectWithActions class. It uses the methods of this class to manipulate any information pertaining to actions for the authentication rule. Do not instantiate directly the ObAMObjectWithActions class because the ObAMAuthenticationRule class inherits it automatically. For details, see "Class ObAMObjectWithActions".

For conceptual information about authentication rules and schemes, including the kinds of challenge methods that can be used to authenticate users, see the Oracle Access Manager Access Administration Guide.

Label	Type	Range	Description
Name (key)	A string Required	Any	A unique name.
Description	A string Optional	Any	A description.
Authentication Scheme	A string Required	Any	An authentication scheme that specifies how credentials are to be obtained and processed.
Action Type	An enumerated value, integer Required	SUCCESS = 0 FAILURE = 1 INCONCLUSIVE = 2 See the class definition .	A value that identifies the type of action that the method applies to. For actions, the ObAMAuthenticationRule uses the methods of the ObAMObjectWithActions class, which it inherits.

Java

public ObAMAuthenticationRule();
  public String getDescription(); 
  public String getScheme();
  public void setDescription(String value); 
  public void setScheme(String value); 
  public void setIDFrom(ObAMObjectWithActions other);
  public int getNumberOfActions(int actionType) throws ObAMException;
  public ObAMAction getActionOfType(int actionType, int index)
                                throws ObAMException;
  public void addActionOfType(int actionTtype, ObAMAction value)
                                throws ObAMException;
  public void removeActionOfType(int actionType, ObAMAction value)
                                throws ObAMException;
  public String getName();
  public void setName(String value);

C Form

typedef const void * ObAMAuthenticationRule_t;
  ObAMAuthenticationRule_t ObAMAuthenticationRule_new();
  ObAMAuthenticationRule_t ObAMAuthenticationRule_copy(
                          ObAMAuthenticationRule_t authn);
  void ObAMAuthenticationRule_delete(
                          ObAMAuthenticationRule_t *pAuthn);
  const char *ObAMAuthenticationRule_getName(
                          ObAMAuthenticationRule_t authn);
  const char *ObAMAuthenticationRule_getDescription(
                          ObAMAuthenticationRule_t authn);
  const char *ObAMAuthenticationRule_getScheme(
                          ObAMAuthenticationRule_t authn);
  void ObAMAuthenticationRule_setIDFrom(
                          ObAMAuthenticationRule_t authn,
                          ObAMAuthenticationRule_t other);
  void ObAMAuthenticationRule_setName(
                          ObAMAuthenticationRule_t authn,const char *value);
  void ObAMAuthenticationRule_setDescription(
                          ObAMAuthenticationRule_t authn,const char *value);
  void ObAMAuthenticationRule_setScheme(
                          ObAMAuthenticationRule_t authn,const char *value);
  int ObAMAuthenticationRule_getNumberOfActions(
                       ObAMObjectWithActions_ActionType type,
                          ObAMAuthenticationRule_t authn);
  ObAMAction_t ObAMAuthenticationRule_getActionOfType(
                          ObAMObjectWithActions_ActionType type,
  ObAMAuthenticationRule_t authn, OBAMAction_t value);
                          ObAMAuthenticationRule_t authn, int index);
  void ObAMAuthenticationRule_removeActionOfType(
                          ObAMObjectWithActions_ActionType type,
                          ObAMAAutbenticationRule_t authn, 
                          ObAMAction_t value);

Creating an Authentication Rule

The code in Example 5-4 creates an authentication rule for the My Domain policy domain object. The code sets the default authentication rule for My Domain to use the Oracle Access and Identity scheme.

The code performs the following functions:

• It creates an ObAMAuthenticationRule object called authnRule to be used for the default authentication rule, and it sets the name of the rule to authnRule.

  ObAMAuthenticationRule authnRule = new;
    ObAMAuthenticationRule();
    authnRule.setName("My Domain Default Authn Rule");
  
  

• It sets the scheme to be used for the default authentication rule to Oracle Access and Identity.

  authnRule.setScheme("Oracle Access and Identity");
  
  

• It defines an action to be performed if authentication of the user is successful, and it adds the action to the default authentication rule.

  authnAction2.setType("otherType");
    authnAction2.setName("authnAction");
    authnAction2.setValue("z");
    authnAction2.setValueType(ObAMAction.FIXEDVALUE);
    authnRule.addSuccessAction(authnAction2);
  

• It adds the default authentication rule to the My Domain policy domain created previously by the application from which this code is excerpted.

  domain.setDefaultAuthenticationRule(authnRule);
  

Example 5-4 Creating a Default Authentication Rule for a Policy Domain

.
                               .
                               .
  ObAMAuthenticationRule authnRule = new ObAMAuthenticationRule();
  authnRule.setName("My Domain Default Authn Rule");
  authnRule.setScheme(ÒOracle Access and IdentityÓ);
  ObAMAction authnAction2 = new ObAMAction();
  authnAction2.setType("otherType");
  authnAction2.setName("authnAction");
  authnAction2.setValue("z");
  authnAction2.setValueType(ObAMAction.FIXEDVALUE);
  authnRule.addSuccessAction(authnAction2);
  domain.setDefaultAuthenticationRule(authnRule);
                               .
                               .
                               .

5.4.23 Class ObAMAuthenticationRuleMgd

(Managed Code). An ObAMAuthenticationRule object specifies how authentication is to be performed for access to resources covered by a policy or policy domain. For details on object class components, see "Class ObAMAuthenticationRule".

Managed Code

// Getters and setters
__property System::String *get_Name();
__property System::String *get_Description();
__property System::String *get_Scheme();
int getNumberOfActions(ObAMActionTypeMgd *action);
ObAMActionMgd *getActionOfType(ObAMActionTypeMgd *type, int index);
__property void set_IDFrom(ObAMAuthenticationRuleMgd *other);
__property void set_Name(System::String *value);
__property void set_Description(System::String *value);
__property void set_Scheme(System::String *value);
void addActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value);
void modifyActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value); 
void removeActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value);

5.4.24 Class ObAMAuthorizationRule

An object of the ObAMAuthorizationRule class specifies the conditions for allowing or denying user access to the resources it protects. An authorization rule contains an authorization scheme. It can also contain actions to be returned depending on the outcome of the attempt to authorize the user requesting access to the protected resource. Actions can be associated with a result of Success or Failure.

An authorization rule can:

• Appear in more than one authorization expression.

• Appear in a single authorization expression more than once.

Any of the authorization rules you create can be used in an authorization expression for a policy domain or any of its policies.

It is the result of evaluation of the expression, that is, all of the rules it contains and the way in which they are combined, that determines the access controls for the protected resources.

For conceptual details on authorization rules and their contents and authorization expression evaluation, see the Oracle Access Manager Access Administration Guide.

Authorization Schemes: An authorization rule must contain an authorization scheme. You can use the default authorization scheme, or you can use a custom one, if any custom authorization schemes have been created. To get a list of existing authorization schemes, you must use the Access System Console. For details about authorization schemes for custom plug-ins and configuring user authorization, see the Oracle Access Manager Access Administration Guide.

About the Names of Authorization Rules and Authorization Expressions: To name an authorization rule, you specify a unique string. You use this string later in an authorization expression for a policy domain and its policies to identify rules an authorization expression contains. (Authorization rules are included in an authorization expression.) For each authorization rule an authorization expression contains, you must specify exactly the string given as the name of the authorization rule. For details, see "About String Names". For details, see "Class ObAMAuthorizationExpr".)

Actions for Authorization Rules: For an authorization rule, you can specify the kinds of actions to be taken based on the result of evaluation of the rule. You can specify actions to be taken if authorization succeeds as a result of the rule or if it fails.

When you create the ObAMAuthorizationRule object, it inherits automatically the ObAMObjectWithActions class, and it uses the methods of the ObAMObjectWithActions class for any functions pertaining to actions. Do not instantiate directly the ObAMObjectWithActions class. For details, see "Class ObAMObjectWithActions".

Not all rules contribute to the result of an authorization expression. Those rules that do participate in the outcome of evaluation of the expression are referred to as determining rules. If a rule is a determining rule, its resulting actions are taken after the expression is evaluated.

Note: In the first version of the Policy Manager API (version 6), custom Authorization Plug-ins are not supported by the Policy Manager engine. For that reason, custom Authorization rules using custom Authorization Plug-ins cannot be created.

Label	Type	Range	Description
Name (key)	A string Required	Any	A unique name. This is the name that you specify in an authorization expression to include the rule in the expression.
Description	A string Optional	Any	A description.
Enabled	A Boolean flag Required	0, meaning no, or other, meaning yes.	Answers the question: Is the rule enabled?
AllowTakes Precedence	A Boolean flag Required	0, meaning no, or other, meaning yes	Answers the question: Do the allow conditions take precedence over the deny conditions?
Timing Conditions	An array of Timing Condition objects Optional	See the class definition .	Timing conditions specifying when the rule is in effect.
ActionType	An enumerated value, integer Required	SUCCESS = 0 FAILURE = 1 INCONCLUSIVE = 2 See the class definition .	A value that identifies the type of action that the method applies to. For actions, the ObAmAuthorizationRule uses the methods of the ObAMObjectWithActions class, which it inherits.
AllowAccess Conditions	One Access Condition object Optional	See the class definition .	Conditions under which access is allowed.
DenyAccess Conditions	One Access Condition object Optional	See the class definition .	Conditions under which access is denied.
Authorization Scheme	A string Optional	Any	The name of a custom or predefined authorization scheme. You must specify the name of an authorization scheme that has already been created. To get a list of authorization schemes, use the Access System Console GUI. If this is provided, then it is illegal to also enter timing and access conditions.
Scheme Parameter	An array of Parameter Objects Optional	See the class definition .	Parameters to be used with a custom Authorization Scheme

Java

public obAMAuthorizationRule();
  public String getName(); 
  public String getDescription(); 
  public boolean getEnabled(); 
  public boolean getAllowTakesPrecedence();
  public int getNumberOfActions(int actionType)
                  throws ObAMException;
  public ObAMAction getActionOfType(int actionType, int index)
                  throws ObAMException;
  public void addActionOftype(int actionType, obAMAction value)
                  throws ObAMException;
  public void removeActionOfType(int actionType, ObAMAction value)
                  throws ObAMException;
  public ObAMTimingConditions getTimingConditions(); 
  public int getNumberOfSchemeParameters();
  public ObAMParameter getSchemeParameter(int index);
  public ObAMAccessConditions getAllowAccessConditions();
  public String getAuthorizationScheme();
  public ObAMAccessConditions getDenyAccessConditions(); 
  public void setName(String value); 
  public void setDescription(String value); 
  public void setEnabled(boolean value); 
  public void setAllowTakesPrecedence(boolean value); 
  public void setTimingConditions(ObAMTimingConditions value); 
  public void setAllowAccessConditions(ObAMAccessConditions value); 
  public void setDenyAccessConditions(ObAMAccessConditions value);
  public void setAuthorizationScheme(String value);
  public void addSchemeParameter(ObAMParameter value);
  public void removeSchemeParameter(ObAMParameter value);
  public void modifySchemeParameter(ObAMParameter value);
  public void setIDFrom(ObAMAuthorizationRule other);

C

typedef const void * ObAMAuthorizationRule_t;
  ObAMAuthorizationRule_t ObAMAuthorizationRule_new()
  ObAMAuthorizationRule_t ObAMAuthorizationRule_copy(
               ObAMAuthorizationRule_t authz);
  void ObAMAuthorizationRule_delete(
               ObAMAuthorizationRule_t *pAuthz);
  const char *ObAMAuthorizationRule_getName(
               ObAMAuthorizationRule_t authz);
  const char *ObAMAuthorizationRule_getDescription(
               ObAMAuthorizationRule_t authz);
  ObAMAuthorizationRule_getEnabled(
               ObAMAuthorizationRule_t authz);
  int ObAMAuthorization_getAllowTakesPrecedence(
               ObAMAuthorizationRule_t authz);
  ObAMTimingConditions_t ObAMAuthorizationRule_getTimingConditions(
               ObAMAuthorizationRule_t authz);
  int ObAMAuthorizationRule_getNumberOfActions(
               ObAMObjectWithActions_ActionType type,
  ObAMAuthorizationRule_t authz);
  ObAMAction_t ObAMAuthorizationRule_getActionOfType(
               ObAMObjectWithActions_ActionType type,
               ObAMAuthorizationRule_t authz, 
               int index);
  ObAMAccessConditions_t
               ObAMAuthorizationRule_getAllowAccessConditions(
               ObAMAuthorizationRule_t authz);
  ObAMAccessConditions_t
               ObAMAuthorizationRule_getDenyAccessConditions(
               ObAMAuthorizationRule_t authz);
  const char *ObAMAuthorizationRule_getAuthorizationScheme(
               ObAMAuthorizationRule_t authz);
  int ObAMAuthorizationRule_getNumberOfSchemeParameters(
               ObAMAuthorizationRule_t authz);
  ObAMParameter_t ObAMAuthorizationRule_getSchemeParameter(
               ObAMAuthorizationRule_t authz, int index);
  void ObAMAuthorizationRule_setIDFrom(
               ObAMAuthorizationRule_t authz,
               ObAMAuthorizationRule_t other);

Obsoleted Methods

ObAMAuthorizationRule_getSuccessAction();
  ObAMAuthorizationRule_getFailureAction();
  ObAMAuthorizationRule_getNumberOfSuccessActions();
  ObAMAuthorizationRule_getNumberOfFailureActions();
  ObAMAuthorizationRule_addSuccessAction();
  ObAMAuthorizationRule_addFailureAction(); 
  ObAMAuthorizationRule_removeSuccessAction();
  ObAMAuthorizationRule_removeFailureAction();

Creating Authorization Rules

The code in Example 5-5 creates an authorization rule and adds it to the My Domain policy domain object. The rule can be used for My Domain's default authorization expression and it can be used for the authorization expressions of any of the policies included in the My Domain policy domain. An application can create many instances of authorization rule objects to be used for a policy domain and its policies.

The code performs the following functions:

• It creates an ObAMAuthorizationRule object called authzRule1. It gives the rule the name Authz Rule 1, and it enables the rule. In the following code segment the rule is named Authz Rule 1. If you were to include this rule in an authorization expression, you would identify it by specifying the string "Authz Rule 1". For details, see Example 5-5, "Creating an Authorization Rule".

  ObAMAuthorizationRule authzRule1 = new
    ObAMAuthorizationRule();
    authzRule1.setName("Authz Rule 1");
    authzRule1.setEnabled(true);
  
  

• It creates an ObAMAccessConditions object called access1 to be used for the rule's access conditions, whether Allow Access or Deny Access is not defined at this point.

  ObAMAccessConditions access1 = new ObAMAccessConditions();
  
  

• It identifies to whom the access conditions apply, two individuals and one group.

  To identify each of these entities, the code:

  • Creates an ObAMIdentity object to set the login ID for the person or group.

  • Adds the person or group to the access1 object (ObAccessObject) of the ObAMAuthorizationRule authorization rule. The code which does this for person1 is shown in the following snippet.

    ObAMIdentity person1 = new ObAMIdentity();
      person1.setLoginID("A.Loomis");
      access1.addPerson(person1);
    

• Adds the access1 object to the Authz Rule 1 (authzRule1) authorization rule object to set its Allow Access conditions.

  authzRule1.setAllowAccessConditions(access1);
  

• Adds the Authz Rule 1 rule to the My Domain policy domain.

  domain.addAuthorizationRule(authzRule1);
  

Example 5-5 Creating an Authorization Rule

ObAMAuthorizationRule authzRule1 = new ObAMAuthorizationRule();
  authzRule1.setName("Authz Rule 1");
  authzRule1.setEnabled(true);
  ObAMAccessConditions access1 = new ObAMAccessConditions();
        
  ObAMIdentity person1 = new ObAMIdentity();
  person1.setLoginID("A.Loomis");
  access1.addPerson(person1);
                        
  ObAMIdentity person2 = new ObAMIdentity();
  person2.setLoginID("E.Lawrence");
  access1.addPerson(person2);
                        
  ObAMIdentity group = new ObAMIdentity();                                         
  group.setName("group1");
  access1.addGroup(group);
  person1.setLoginID("admin");
  access1.addPerson(person1);
                        
  authzRule1.setAllowAccessConditions(access1);
  ObAMAction action1 = new ObAMAction();
  action1.setType("headerVar");
  action1.setName("UserIs");
  action1.setValue("uid");
  action1.setValueType(ObAMAction.ATTRIBUTE);
  authzRule1.addActionOfType(ObAMObjectWithActions.SUCCESS, action1);
 
  domain.addAuthorizationRule(authzRule1);

5.4.25 Class ObAMAuthorizationRuleMgd

(Managed Code). An ObAMAuthorizationRule specifies the conditions for allowing or denying access to resources covered by a policy or policy domain. For details on the object class components, see Class ObAMAuthorizationRule .

Note: In the first version of the Policy Manager API (version 6), custom Authorization Plug-ins are not supported by the Policy Manager engine. For that reason, custom Authorization rules using custom Authorization Plug-ins cannot be created.

Managed Code Form

// Getters and setters
__property System::String *get_Name();
__property System::String *get_Description();
__property bool get_Enabled();
__property bool get_AllowTakesPrecedence();
__property ObAMTimingConditionsMgd *get_TimingConditions();
int getNumberOfActions(ObAMActionTypeMgd *action, int index);
ObAMActionMgd *getActionOfType(ObAMActionTypeMgd *action, int index);
__property ObAMAccessConditionsMgd *get_AllowAccessConditons();
__property ObAMAccessConditionsMgd *get_DenyAccessConditons();
__property System::String *get_AuthorizationScheme();
__property int get_NumberOfSchemeParameters();
ObAMParameterMgd *getSchemeParameter(int index);
__property void set_IDFrom(ObAMAuthorizationRuleMgd *other);
__property void set_Name(System::String *value);
__property void set_Description(System::String *value);
__property void set_Enabled(bool value);
__property void set_AllowTakesPrecedence(bool value);
__property void set_TimingConditions(ObAMTimingConditionsMgd *value);
__property void set_AllowAccessConditions(ObAMAccessConditionsMgd *value);
__property void set_DenyAccessConditions(ObAMAccessConditionsMgd *value);
void addActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value);
void modifyActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value);
void removeActionOfType(ObAMActionTypeMgd *action, ObAMActionMgd *value);

5.4.26 Class ObAMAuthorizationExpr

An object of the ObAMAuthorizationExpr class specifies an authorization expression. An authorization expression can consist of one or more authorization rules, specifying a simple or complex condition whose evaluation determines whether a user is granted access to a resource protected by the expression. In addition to authorization rules, an authorization expression contains symbols representing different ways to combine, and thus evaluate, the rules of the expression. You include in an authorization expression the names of the authorization rules you want to use.

It is an authorization expression that is included in a policy domain or a policy. Every policy domain must include a single authorization expression. A policy can include an authorization expression, but it is not a requirement. If it does not, the default authorization expression created for the policy domain is used for the policies resources.

Rules of an authorization expression can be combined in various ways to express particular authorization requirements. It is the result of the Access Server's evaluation of the authorization expression that determines if a user is given access to the requested resource.

An authorization expression includes:

• The authorization rules controlling user access to resources. If the expression contains more than one rule, the + and | symbols are used to specify how the rules are to be interpreted. For details on the content of authorization rules and how to use the + and | symbols to create the logic of the expression, see the Oracle Access Manager Access Administration Guide.

• A policy for dealing with duplicate actions.

• Optional actions to be performed by the client if evaluation of the expression succeeds, if it fails, or if the result is inconclusive.

About the Symbols Used in an Authorization Expression: If an authorization expression contains more than one authorization rule, you must include in it the symbols that specify the way in which those rules are combined and are to be interpreted for users requesting access to the protected resources. These symbols include + (AND) and | (OR) and parenthesis. They are referred to as operators. In the Policy Manager GUI, either AND and OR can be specified or the symbols + and | can be specified as operators. However, for the Policy Manager API, you must use the symbols. For further explanation about the symbols and modifying an authorization scheme, see the Oracle Access Manager Access Administration Guide.

How Authorization Expressions Are Interpreted: It is possible to create complex authorization expressions. For this reason, it is important to understand how the Access System interprets those expressions in regard to precedence of operators and position of rules within the expression. For details about evaluation of the rules of an expression and configuring user authorization, see the Oracle Access Manager Access Administration Guide.

About an Expression Result of Inconclusive: If an expression evaluates to a result of Inconclusive, the Access System returns a major status code of Deny and a minor status code of Inconclusive. The minor status code of Inconclusive enables those systems to distinguish between true Deny results and Deny results returned because of an Inconclusive state.

An authorization expression result of Deny differs from an authorization expression result of Inconclusive even though the user is denied access to the requested resource in both cases. Making this distinction gives you, as a developer, more options. For example, an application can interpret the two status codes for an Inconclusive result and use the additional information for other purposes. The application might then invoke other authorization engines instead of denying the user access to the resource.

Actions for an Authorization Expression: An authorization expression can have associated with it actions to be taken based on the result of evaluation of the expression. When it is created, the ObAMAuthorizationExpr objects inherits automatically the ObAMObjectWithActions class--do not directly instantiate this class.

The ObAMAuthorizationExpr object uses the methods of the ObAMObjectWithActions class to manipulate actions associated with it. These actions include

• Success Actions

• Failure Actions

• Inconclusive Actions

  An authorization expression is evaluated to a result of Inconclusive if the rules of the expression produce conflicting results. In this case the user is denied access to the resource. However, your application can use this information.

About the Result of an Authorization Expression and Actions Returned: It is important to understand which actions are returned after evaluation of an authorization expression. The actions of only those rules that contributed to the result of evaluation of the expression are returned. These rules are referred to as definitive rules. Because the concept of definitive rules is complex, you should review the explanation and examples in discussions on authorization rule evaluation and configuring user authorization in the Oracle Access Manager Access Administration Guide.

Duplicate Actions Policy: Because an authorization rule can be reused within an authorization expression, it is possible that evaluation of each instance of the authorization rule producing the same result can cause the Access Server to return the same action more than once. It is also possible that different rules of an expression could return the same actions. Conflict can occur when, as a result of evaluation of the expression, two or more rules contributing to the definitive result produce the same actions. You can set the policy for how duplicate actions are to be handled, if any occur. For this purpose, you use the following values

• ACTION_DUPLICATE = 0

• ACTION_IGNORE = 1

• ACTION_OVERWRITE = 2

• UNDEFINED = 3

Here is how these values are interpreted:

• ACTION_DUPLICATE: If you choose this option, the Access Server appends each new value it encounters to the information it returns to the application requesting authorization for the user. (The Access Server does not check for duplicate information.) Select this option if the application expects to receive information for all instances of the action. In this case, the application must process the values of all duplicate actions returned to it. Use of this option may incur performance issues.

• ACTION_IGNORE: If you chose this option, the Access Server removes all duplicate actions, and only the first instance of the action is returned to the application requesting authorization for the user. Each time an action value is added, the Access Server checks existing values to determine if the new action duplicates an existing one. If the Access Server finds one, it does not add the new value to those it returns to the application. In this case, any information inherent to the value of the repeated action is lost. Because the Access Server must check for duplicate actions, use of this option may incur performance costs

• ACTION_OVERWRITE: If you choose this option, only the value of the last instance of the action is returned. Each new value overwrites the previous one, and previous values are lost. Do not select this option if the application requesting the authorization expects the results of all duplicate actions. This option is the most efficient one.

Duplicate Actions and WebGate Restrictions: The ability to process duplicate actions applies to AccessGates only. The Access Server sends to the WebGate the actions as specified by the duplicate actions policy, whether Duplicate, Ignore Duplicate, or Overwrite. However, the WebGate supports only a single value for each header variable. Although it receives the duplicate actions, the WebGate overrides duplicates such that the last value set for the header variable is used. Values set for the same header variable by previous actions are lost.

Label	Type	Range	Description
Authorization Expression	A string Required	Any	An expression containing one or more authorization rules, specified by name, and the symbols used to combine them.
Name (key)	A string Required	Any	A unique name.
Description	A string Optional	Any	A description.
Enabled	A Boolean flag Required	0, meaning no, or other, meaning yes.	Answers the question: Is the rule enabled?
Duplicate Actions Policy	A string Optional	Any one of the following constants: ACTION_DUPICATE = 0 (Duplicate) ACTION_IGNORE = 1 (Ignore) ACTION_OVERWRITE = 2 (Overwrite) UNDEFINED = 3	The policy for the Access Server to follow if it encounters duplicate actions as a result of evaluation of this expression.
Success Actions	An array of Action objects Optional	See the class definition .	Actions to be performed by the client if authorization succeeds as a result of evaluation of the expression. The ObAmObjectWithActions class is used to manage success actions.
Failure Actions	An array of Action objects Optional	See the class definition .	Actions to be performed by the client if the authorization fails and the user is denied access as a result of evaluation of the expression. The ObAMObjectWithActions class is used to manage failure actions.
Inconclusive Actions	An array of Action objects Optional	See the class definition .	Actions to be performed by the client if authorization cannot be conclusively determined as a result of evaluation of the expression. In this case, the user is denied access to the resource. The ObAmObjectWithActions class is used to manage success actions.

Java

public ObAMAuthorizationExpr(); 
  public String getExpression(); 
  public void setExpression(String value)throws ObAMException; 
  public int getDuplicateActionsPolicy(); 
  public void setDuplicateActionsPolicy(int value)throws ObAMException; 
  public int getNumberOfActions(int actionType)throws ObAMException;
  public ObAMAction getActionOfType(int actionType,int index)throws ObAMException;
  public void addActionOfType(int actionType,
  ObAMAction value) throws ObAMException;
  public void removeActionOfType(int actionType,
  ObAMAction value) throws ObAMException;
  public String getName();
  public void setName(String value); 
  public void setIDFrom(ObAMObjectWithActions other);

C

typedef const void * ObAMAuthorizationExpr_t;
  ObAMAuthorizationExpr_t ObAMAuthorizationExpr_new();
  ObAMAuthorizationExpr_t ObAMAuthorizationExpr_copy(
          ObAMAuthorizationExpr_t authz);
  void ObAMAuthorizationExpr_delete(
          ObAMAuthorizationExpr_t *pAuthz);
  const char *ObAMAuthorizationExpr_getExpr(
          ObAMAuthorizationExpr_t authz);
  int ObAMAuthorizationExpr_getDuplicateActionsPolicy(
          ObAMAuthorizationExpr_t authz);
  int ObAMAuthorizationExpr_getNumberOfActions(
          ObAMObjectWithActions_ActionType type,
          ObAMAuthorizationExpr_t authz);
  ObAMAction_tObAMAuthorizationExpr_getActionOfType(
          ObAMObjectWithActions_ActionType type,
          ObAMAuthorizationExpr_t authz, int index);
  void ObAMAuthorizationExpr_setIDFrom(
          ObAMAuthorizationExpr_t authz,
          ObAMAuthorizationExpr_t other);
  void ObAMAuthorizationExpr_setExpr(
          ObAMAuthorizationExpr_t authz, const char *value);
  voidObAMAuthorizationExpr_setDuplicateActionsPolicy(
          ObAMAuthorizationExpr_t authz,
          ObAMAuthorizationExpr_DuplicateActionsPolicy value);

Creating an Authorization Expression

Example 5-6 shows a portion of an example program. This code creates a default authorization expression for a policy domain. It performs the following functions:

• It creates an ObAMAuthorizationExpr object called pd_expr and specifies the content of the expression, that is, the authorization rules of the expression and how they are combined in the expression.

  ObAMAuthorizationExpr pd_expr =new ObAMAuthorizationExpr();
    pd_expr.setExpression ("Authz Rule 1 & Authz Rule 2");
  
  

• It sets the duplicate actions policy for the expression to OVERWRITE.

  pd_expr.setDuplicateActionsPolicy(ObAMAuthorizationExpr.ACTION_OVERWRITE);
  
  

• It creates an ObAMAction object to be used for an action. Using the object, it defines an action to be taken if the result of evaluation of the expression is Inconclusive.

  ObAMAction action3 = new ObAMAction();
    action3.setType("otherType");
    action3.setName("authzAction");
    action3.setValue("a");
    action3.setValueType(ObAMAction.FIXEDVALUE);
  
  

• It adds the Inconclusive action to the authorization expression

  pd_expr.addActionOfType( ObAMObjectWithActions.INCONCLUSIVE, action3);
  
  

• It adds the authorization expression to the policy domain.

  domain.setDefaultAuthorizationExpr(pd_expr);
  

Example 5-6 Creating an Authorization Expression

.
                          .
                          .
  ObAMAuthorizationExpr pd_expr = new ObAMAuthorizationExpr();
  pd_expr.setExpression("Authz Rule 1 & Authz Rule 2");
  pd_expr.setDuplicateActionsPolicy(ObAMAuthorizationExpr.ACTION_OVERWRITE);
  ObAMAction action3 = new ObAMAction();
  action3.setType("otherType");
  action3.setName("authzAction");
  action3.setValue("a");
  action3.setValueType(ObAMAction.FIXEDVALUE);
  pd_expr.addActionOfType(ObAMObjectWithActions.INCONCLUSIVE, action3);
  domain.setDefaultAuthorizationExpr(pd_expr);
                        .
                        .
                        .

5.4.27 Class ObAMAuthorizationExprMgd

(Managed Code). This class defines a managed authorization expression. It specifies the conditions for allowing or denying access to resources covered by a policy or policy domain.

Managed Code Form

__property System::String *get_Expr();
__property int get_DuplicateActionsPolicy();
int getNumberOfActions(ObAMActionTypeMgd *type);
ObAMActionMgd *getActionOfType(ObAMActionTypeMgd *type,int index);                                                    
__property void set_Expr(System::String *value);
void setDuplicateActionsPolicy(ObDuplicationActionPolicyMgd *value);
void addActionOfType(ObAMActionTypeMgd *type, ObAMActionMgd *value);
void modifyActionOfType(ObAMActionTypeMgd *type,ObAMActionMgd *value);
void removeActionOfType(ObAMActionTypeMgd *type,ObAMActionMgd *value);

5.4.28 Class ObAMDuplicateActionPolicyMgd

(Managed Code). Class used to describe the policy for dealing with duplicate actions. The choices are to duplicate, ignore, overwrite, or undefined.

Managed Code Form

void setDuplicate();
  void setIgnore();
  void setOverWrite();
  void setUndefined();

5.4.29 Class ObAMAccessConditions

An object of the ObAMAccessConditions class specifies for an authorization rule the conditions under which access is allowed or denied to the protected resource.

Label	Type	Range	Description
Role (no key)	An array of strings At least one required	One of: none anyone noone	A set of roles
Person	An array of Identity objects Optional	See the class definition .	A set of people against which the user requesting access is compared
Group	An array of Identity objects Optional	See the class definition .	A set of groups against which the user is compared
Rule	An array of strings At least one required	Any	A set of LDAP rules that select user profiles
IPAddress	An array of strings At least one required	Any	A set of IP addresses against which the user's IP address is compared

Java

public int getNumberOfPersons(); 
  public int getNumberOfGroups(); 
  public int getNumberOfRoles(); 
  public int getNumberOfRules(); 
  public int getNumberOfIPaddresses(); 
  public ObAMIdentity getPerson(int index); 
  public ObAMIdentity getGroup(int index); 
  public String getRole(int index); 
  public String getRule(int index); 
  public String getIPaddress(int index); 
  public void addRole(String value); 
  public void addPerson(ObPerson value); 
  public void addGroup(ObGroup value); 
  public void addRule(String value); 
  public void addIPAddress(String value); 
  public void removeRole(String value); 
  public void removePerson(ObPerson value); 
  public void removeGroup(ObGroup value); 
  public void removeRule(String value); 
  public void removeIPAddress(String value);
  public void setIDFrom(ObAMAccessConditions other);

5.4.30 Class ObAMAccessConditionsMgd

(Managed Code). An ObAMAccessConditionsMgd object specifies the conditions under which access is allowed or denied in an authorization rule. For details on object components, see "Class ObAMAccessConditions".

Managed Code

// Getters and setters
  _property int get_NumberOfPersons();
  _property int get_NumberOfGroups();
  _property int get_NumberOfRoles();
  _property int get_NumberOfRules();
  _property int get_NumberOfIPaddresses();
  ObAMIdentityMgd *getPerson (int index);
  ObAMIdentityMgd *getGroup (int index);
  System::String *getRole(int index);
  System::String *getRule(int index);
  System::String *getIPaddress(int index);
  _property void set_IDFrom(ObAMAccessConditionsMgd *access);
  _property void set_AddRole(System::String *value);
  _property void set_AddPerson(ObAMIdentityMgd *value);
  _property void set_AddGroup(ObAMIdentityMgd *value);
  _property void set_AddRule(System::String *value);
  _property void set_AddIPaddress(System::String *value);
  _property void set_RemoveRole(System::String *value);
  _property void set_RemovePerson(ObAMIdentityMgd *value);
  _property void set_RemoveGroup(ObAMIdentityMgd *value);
  _property void set_RemoveRule(System::String *value);
  _property void set_RemoveIPaddress(System::String *value);

5.4.31 Class ObAMActionTypeMgd

(Managed Code). Class used to describe the type of action being requested. The set methods are used to define the type of action requested.

Managed Code

void setSuccess();
  void setFailure();
  void setInconclusive();

5.4.32 Class ObAMObjectWithActions

The ObAMObjectWithActions class is an abstract class that is inherited by the ObAMAuthenticationRule class, the ObAMAuthorizationRule class, and the ObAMAuthorizationExpr class when they are instantiated. Do not instantiate this class directly.

You use the methods of this class to get and set information about actions for objects of any of these other classes. The ObAMObjectWithActions class methods allow you to specify the kind of action you are interested in. The class defines an enumeration to specify the three types of actions: Success, Failure, and Inconclusive.

Label	Type	Range	Description
Name	String, Optional	any	The name of the authorization expression object
Action Type	An enumerated value, Integer	SUCCESS = 0 FAILURE = 1 INCONCLUSIVE = 2 See the class definition .	A value that identifies the type of action that the method applies to. The types apply in the following way: For ObAMAuthenticationRule An authentication rule can have associated with it SUCCESS actions and FAILURE actions. For ObAMAuthorizationRule An authorization rule can have associated with it SUCCESS actions and FAILURE actions. For ObAMAuthorizationExpr An authorization expression can have associated with it SUCCESS, FAILURE, and INCONCLUSIVE actions.

Java

public int getNumberOfActions(int actionType)
          throws ObAMException;
  public ObAMAction getActionOfType(int actionType, int index)
          throws ObAMException;
  public void addActionOfType (int actionType, ObAMAction value) 
          throws ObAMException;
  public void removeActionOfType(int actionType, ObAMAction value) 
          throws ObAMException;
  public String getName();
  public void setName(String value);
  public void setIDFrom(ObAMObjectWithActions other);

5.4.33 Class ObAMTimingConditions

An authorization rule can include timing conditions that set the period of time when the rule is in effect. If you do not set a timing condition, by default the authorization rule is always in effect. Timing conditions affect both the Allow Access and the Deny Access conditions of the rule.

An object of the ObAMTimingConditions class contains timing conditions specifying when the rule is in effect.

Label	Type	Range	Description
RelativeTo (no key)	Integer Optional	UNDEFINED=0 GMT=1 LOCAL_TIME=2	A flag indicating whether the timing conditions are relative to GMT or local time
StartDate	A single Date object Optional	See the class definition .	A start date for the period during which the Timing Condition applies
StartTime	A single Time object Optional	See the class definition .	A start time for the period during which the Timing Condition applies
EndDate	A single Date object Optional	See the class definition .	An end date for the period during which the Timing Condition applies
EndTime	A single Time object Optional	See the class definition .	An end time for the period during which the Timing Condition applies
Months	An array of strings Optional	See the list of valid month values under Date objects .	Sets of months
DayofMonth	An array of strings Optional	See the list of valid day values under Date objects.	Sets of days of the month
DayofWeek	An array of strings Optional	See the discussion for this value under Date objects.	Sets of days of the week.

Java

public int getRelativeTo(); 
  public ObAMDate getStartDate(); 
  public ObAMTime getStartTime(); 
  public ObAMDate getEndDate(); 
  public ObAMTime getEndTime(); 
  public int getNumberOfMonths(); 
  public int getNumberOfDaysOfMonth(); 
  public int getNumberOfDaysOfWeek(); 
  public int getMonth(int index); 
  public int getDayOfMonth(int index); 
  public int getDayOfWeek(int index); 
  public void setRelativeTo(int value)throws ObAMException; 
  public void setStartDate(ObAMDate value); 
  public void setStartTime(ObAMTime value); 
  public void setEndDate(ObAMDate value); 
  public void setEndTime(ObAMTime value) 
  public void addMonth(int value)throws ObAMException; 
  public void addDayOfMonth(int value)throws ObAMException; 
  public void addDayOfWeek(int value)throws ObAMException; 
  public void removeMonth(int value)throws ObAMException; 
  public void removeDayOfMonth(int value)throws ObAMException; 
  public void removeDayOfWeek(int value)throws ObAMException;
  public void setIDFrom(ObAMTimingConditions other);

The code in Example 5-7 creates an authorization rule and sets the timing conditions for it. The code performs the following functions:

• It creates an ObAMAuthorizationRule object called authzRule2, sets the name member of the object to Authz Rule 2, and it enables the rule.

  ObAMAuthorizationRule authzRule2 = new ObAMAuthorizationRule();
    authzRule2.setName("Authz Rule 2");
    authzRule2.setEnabled(true);
  
  

• It creates an ObAMTimingConditions object called timing2 to be used for the rule's timing conditions.

  ObAMTimingConditions timing2 = new ObAMTimingConditions();
  
  

• It creates an ObAMDate object called startDate to specify the date beginning from which the rule is applicable. It creates an ObAMTime object to specify the time beginning from which the rule applies. It sets the starting date and it sets the starting time in these objects.

  ObAMDate startDate = new ObAMDate();
    ObAMTime startTime = new ObAMTime();
    startDate.set(2001, ObAMDate.OCTOBER, 31);
    startTime.set(12, 0, 0);
  
  

• It specifies that the time is relative to the local time on the Web server.

  timing2.setRelativeTo(ObAMTimingConditions.LOCAL_TIME);
  
  

The remainder of the code sets the timing conditions to allow anyone access after 12:00:00 of October 15, 2001 on the 1st, 2nd, and 30th of January and November if the day is either a Monday or a Tuesday.

Example 5-7 Creating an Authorization Rule with Timing Conditions

.
                        .
                        .
  ObAMAuthorizationRule authzRule2 = new ObAMAuthorizationRule();
  authzRule2.setName("Authz Rule 2") ;
  authzRule2.setEnabled(true);
  ObAMTimingConditions timing2 = new ObAMTimingConditions();
  ObAMDate startDate = new ObAMDate();
  ObAMTime startTime = new ObAMTime();
  startDate.set(2001, ObAMDate.OCTOBER, 31);
  startTime.set(12, 0, 0);
  timing2.setRelativeTo(ObAMTimingConditions.LOCAL_TIME);
  timing2.setStartDate(startDate);
  timing2.setStartTime(startTime);
  timing2.addMonth(ObAMDate.JANUARY);
  timing2.addMonth(ObAMDate.NOVEMBER);
  timing2.addDayOfMonth(1);
  timing2.addDayOfMonth(2);
  timing2.addDayOfMonth(30);
  timing2.addDayOfWeek(ObAMDate.MONDAY);
  timing2.addDayOfWeek(ObAMDate.TUESDAY);
  authzRule2.setTimingConditions(timing2);
                  .
                  .
                  .

5.4.34 Class ObAMTimingConditionsMgd

An object of the ObAMTimingConditions class contains timing conditions to be set for an authorization rule to specify when that rule is in effect.

Label	Type	Range	Description
StartDate	A single Date object Optional	See the class definition .	A start date for the period during which the Timing Condition applies
StartTime	A single Time object Optional	See the class definition .	A start timefor the period during which the Timing Condition applies
EndDate	A single Date object Optional	See the class definition .	An end date for the period during which the Timing Condition applies
EndTime	A single Time object Optional	See the class definition .	An end time for the period during which the Timing Condition applies
Months	An array of strings Optional	See the list of valid month values under Date objects .	Sets of months
DayofMonth	An array of strings Optional	See the list of valid day values under Date objects .	Sets of days of the month
DayofWeek	An array of strings Optional	See the discussion for this value under Date objects .	Sets of days of the week.

In addition to the other settings for timing conditions, the class ObAMTimingConditionsMgd indicates whether the timing conditions are relative to GMT or local time. See "Class ObAMTimingConditions_RelativeToMgd" for details.

Managed Code Form

// Getters and setters
_property ObAMDateMgd *get_StartDate();
_property ObAMTimingConditions_RelativeToMgd *get_RelativeTo();
_property ObAMTimeMgd *get_StartTime();
_property ObAMTimeMgd *get_EndDate();
_property ObAMTimeMgd *get_EndTime();
_property int get_NumberOfMonths();
_property int get_NumberOfDaysOfMonth();
_property get_NumberofDaysOfWeek();
int getMonth(int index);
int getDayOfMonth(int index);
int getDayOfWeek(int index);
_property void set_IDFrom(ObAMTimingConditionsMgd *other);
_property void set_RelativeTo(ObAMTimingConditions_RelativeToMgd*value);
_property void set_StartDate(ObAMDateMgd *date);
_property void set_EndTime(ObAMTimeMgd *time);
_property void set_EndDate(ObAMDateMgd *date);
_property void set_StartTime(ObAMDateMgd *time);
_property void set_AddMonth(ObAMDate_MonthsMgd *value);
_property void set_AddDayOfMonth(int value);
_property void set_AddDayOfWeek(ObAMDate_DaysOfWeekMgd *value);
_property void set_RemoveMonth(ObAMDate_MonthsMgd *value);
_property void set_RemoveDayOfMonth(int value);
_property void set_RemoveDayOfWeek(ObAMDate_DaysOfWeekMgd *value);

5.4.35 Class ObAMTimingConditions_RelativeToMgd

(Managed Code). This class defines a managed value type for defining the various timing conditions used by the ObAMTimingConditionsMgd class. This class provides a wrapper around the enum ObAMTimingConditions_RelativeTo. You can either set the value using the setter methods, or you can use an ObAMTimingConditions_RelativeTo value.

The methods for this class are as follows:

setUndefined() = UNDEFINED
setGMT() = GMT
setLocalTime() = LOCAL_TIME

Managed Code Form

// Getters and setters
_property bool get_isUndefined();
_property bool get_isGMT();
_property bool get_isLocalTime();
_property ObAMTimingConditions_RelativeTo get_Value();
void setUndefined();
void setAsGMT();
void setAsLocalTime();

5.4.36 Class ObAMDate_DaysOfWeekMgd

(Managed Code). This is a wrapper around unmanaged enum of days of the week. Use this class to define a day of the week when setting timing conditions.

Managed Code Form

ObAMDate_DaysOfWeekMgd();
    void setSunday();
    void setMonday();
    void setTuesday();
    void setWednesday();
    void setThursday();
    void setFriday();
    void setSaturday();

5.4.37 Class ObAMAction

An object of the ObAMAction class represents an action to be returned on success or failure of an authentication or authorization process. The action is interpreted by a WebGate or other Access Client.

Label	Type	Range	Description
Type (key1)	A string Required	Any f the values: redirectURL headerVars custom	A type indicating what action should be taken
Name (key2)	A string Required	Any	The action name
Value	A string Required	Any	The action value
ValueType	A string Required	Any	The type of the value, which can be a fixed value or a user attribute

Java

public String getType(); 
  public String getName(); 
  public String getValue(); 
  public int getValueType(); 
  public void setType(Stromg value); 
  public void setName(String value); 
  public void setValue(String value); 

5.4.38 Class ObAMActionMgd

(Managed Code). An ObAMActionMgd class represents an action to be performed on a successful or failed authentication or authorization. The action is interpreted by a WebGate or other Access Client.

Label	Type	Range	Description
Type (key1)	A string Required	Any of the values: redirectURL headerVars custom	A type indicating what action should be taken
Name (key2)	A string Required	Any	The action name
Value	A string Required	Any	The action value
ValueType	A string Required	Any	The type of the value, which can be a fixed value or a user attribute

Managed CodeForm

// Getters and Setters
_property System::String *get_Type();
_property System::String *get_Name();
_property System::String *get_value();
_property ObAMAction_ValueTypeMgd *get_ValueType();
_property void set_IDFrom(ObAMActionMgd *other);
_property void set_Type(System::String *value);
_property void set_Name(System::String *value);
_property void set_Value(System::String *value);
_property void set_ValueType(ObAMAction_ValueTypeMgd *value);

5.4.39 Class ObAMAction_ValueTypeMgd

(Managed Code). An ObAMAction_ValueTypeMgd object represents the value types used by the ObAMActionMgd class. This class provides a wrapper around the enum ObAMAction_ValueType.

Managed CodeForm

// Getters and Setters
_property bool get_isUndefined();
_property bool get_isFixedValue();
_property bool get_isAttribute();
_property obAMAction_ValueType get_Value();
_property void set_Value(ObAMAction_ValueType value);
void setUndefined();
void setFixedValue();
void setAttribute();

5.4.40 Class ObAMAuditRule

An object of the ObAMAuditRule class defines the kind of auditing to be done for a policy or policy domain.

Label	Type	Range	Description
Events (no key)	An array of strings At least one required	See the list provided for Master Audit Rule .	A set of events for which audit records will be generated
Attributes	An array of strings At least one required	Any	A set of user profile attributes to be included in the audit records

Java

public int getNumberOfEvents();
  public int getNumberOfAttributes(); 
  public int getEvent(int index);
  public String getAttribute(int index); 
  public void addEvent(int value);
  public void addAttribute(String value); 
  public void removeEvent(int value); 
  public void removeAttribute(String value);
  public void setIDFrom(ObAMAuditRule other);

5.4.41 Class ObAMAuditRuleMgd

(Managed Code). An ObAMAuditRuleMgd object specifies how auditing is to be done for a policy or policy domain.

Label	Type	Range	Description
Events (no key)	An array of strings At least one required	See the list provided for Master Audit Rule	A set of events for which audit records will be generated
Attributes	An array of strings At least one required	Any	A set of user profile attributes to be included in the audit records

Managed Code Form

// Getters and setters
__property int get_NumberOfEvents();
__property int get_NumberOfAttributes();
ObAMAuditRule_EventTypeMgd *getEvent(int index);
System::String *getAttribute(int index);
__property void set_IDFrom(ObAMAuditRuleMgd *other);
__property void set_AddEvent(ObAMAuditRule_EventTypeMgd *value);
__property void set_AddAttribute(System::String *value);
__property void set_RemoveEvent(ObAMAuditRule_EventTypeMgd *value);
__property void set_RemoveAttribute(System::String *value);

5.4.42 Class ObAMAuditRule_EventTypeMgd

(Managed Code). This is a Managed Value Type class that defines the event types used by the ObAuditRuleMgd class. This class provides a wrapper around the enum ObAMAuditRule_eventType. You may either set the value using the setter methods, or use an ObAMAuditRule_EventType value.

Managed Code Form

// Get and set values
__property bool get_isUndefined();
__property bool get_isAuthenticationSuccess();
__property bool get_isAuthenticationFailure();
__property bool get_isAuthorizationSuccess();
__property bool get_isAuthorizationFailure();
__property ObAMAuditRule_EventType get_Value();
__property void set_Value(ObAMAuditRule_EventType value);
void setUndefined();
void setAuthenticationSuccess();
void setAuthenticationFailure();
void setAuthorizationSuccess();
void setAuthorizationFailure();

5.4.43 Class ObAMDate

An object of the ObAMDate class represents a date. The ObAMDate class includes one set method to set the year, month, and day. If the date or time is invalid, the method throws an ObAMException with the BAD_OBJECT code.

Label	Type	Range	Description
Year (no key)	Integer Required	The full year	An integer representing the year value in the object
Month	Integer Required	One of an enumerated list, as follows: JANUARY=1 FEBRUARY=2 MARCH=3 APRIL=4 MAY=5 JUNE=6 JULY=7 AUGUST=8 SEPTEMBER=9 OCTOBER=10 NOVEMBER=11 DECEMBER=12	An integer representing the month value in the object
Day	Integer Required	One of an enumerated list, as follows: SUNDAY=1 MONDAY=2 TUESDAY=3 WEDNESDAY=4 THURSDAY=5 FRIDAY=6 SATURDAY=7	An integer representing the day value in the object

Java

public int getYear(); 
  public int getMonth(); 
  public int getDay();

5.4.44 Class ObAMDateMgd

(Managed Code) An ObAMDateMgd object represents a date. The ObAMDateMgd class has one set method to set the year, month, and day. If the date or time is invalid, set will throw an ObAMException with the BAD_OBJECT code. For details on the object components, see "Class ObAMDate".

Managed Code Form

// Getters and setters
_property int get_Year();
_property int get_Month();
_property int get_Day();
void set(int year, int month, int day_);

5.4.45 Class ObAMDate_MonthsMgd

Use this class to define months of the year when setting timing conditions.

Managed Code Form

ObAMDate_MonthsMgd();
void setJanuary();
void setFebruary();
void setMarch();
void setApril();
void setMay();
void setJune();
void setJuly();
void setAugust();
void setSeptember();
void setOctober();
void setNovember();
void setDecember();

5.4.46 Class ObAMDate_DaysOfWeekMgd

Use this class to define days of the week when setting the timing conditions (using ObAMATimingConditionsMgd class) or setting the date (using the ObAMADateMgd class).

Managed Code Form

ObAMDate_DaysOfWeekMgd();
void setSunday();
void setMonday();
void setTuesday();
void setWednesday();
void setThursday();
void setFriday();
void setSaturday();

5.4.47 Class ObAMIdentity

An object of the ObAMIdentity class identifies a user or group profile in the user directory used in an access condition or an admin rule.

Label	Type	Range	Description
UID (no key)	A string Required	Any	A unique ID for the identity
Name	A string Required	Any	A name
LoginID	A string Required	Any	A login ID, as defined by the person object class in the Identity System. Empty for group identities.

Java

public String getUID(); 
  public String getName(); 
  public String getLoginID(); 
  public void setUID(String value); 
  public void setName(String value); 
  public void setLoginID(String value);
  public void serialize(String value); 

Note: For an Identity object, the Name member is strictly a label and does not correspond to a directory entry. For that reason, an ObAMIdentityObject for which only the Name has been set cannot be added to any other object.

5.4.48 Class ObAMIdentityMgd

(Managed Code). An ObAMIdentityMgd object identifies a user or group profile in the user directory used in an access condition or an admin rule.

Label	Type	Range	Description
UID (no key)	A string Required	Any	A unique ID for the identity
Name	A string Required	Any	A name
LoginID	A string Required	Any	A login ID, as defined by the person object class in the Identity System. Empty for group identities.

Managed Code Form

// Getters and setters
_property System::String *get_UID();
_property System::String *get_Name();
_property System::String *get_LoginID();
_property ObAMIdentity *get_UnmanageIdentity();
_property void set_UID(System::String *value);
_property void set_Name(System::String *value);
_property void set_LoginID(System::String *value);

Note: Unique to the Identity object, the Name member is strictly a label and does not correspond to a directory entry. For that reason, an ObAMIdentityObjectMgd for which only the Name has been set cannot be added to any other object.

5.4.49 Class ObAMParameter

An object of the ObAMParameter class supplies a name-value pair to be matched against request data (for example, an HTTP query string or POST data) when determining if a policy applies to an access request. ObAMParameter objects are also used in authorization schemes.

Label	Type	Range	Description
Name (key)	A string Required	Any	A name
Value	A string Required	Any	A value for the name

Java

public String getName();
  public String getValue();
  public void setName(String value);
  public void setValue(String value);

5.4.50 Class ObAMParameterMgd

(Managed Code) An ObAMParameterMgd object supplies a name-value pair to be matched against request data (for example, an HTTP query string or POST data) when determining if a policy applies to an access request. ObAMParameterMgd objects are also used in authorization schemes. For details on the object components, see "Class ObAMParameter".

Managed Code

// Getters and setters
_property System::String *get_Value();
_property System::String *get_Name();
_property void set_Name(System::String *value);
_property void set_Value(System::String *value);

5.4.51 Class ObAMResource

An object of the ObAMResource class represents a set of resources to which policy domains or policies apply. The resource set is selected by matching components of the Resource URL to ObAMResource members.

Label	Type	Range	Description
ResourceType (key1)	A string Required	Any	A built-in or custom resource type
HostID (key2)	A string Required	Any	A host ID that specifies a set of host names, IP address, and ports
URLPrefix (key3)	A string Required	Any	A URL prefix that matches the initial local part of the URL
Description	A string Optional	Any	An optional description

Java

public String getResourceType();
  public String getHostID();
  public String getURLPrefix();
  public String getDescription();
  public void setResourceType(String value);
  public void setHostID(String value);
  public void setURLPrefix(String value);
  public void setDescription(String value);
  public void setIDFrom(ObAMResource other);

5.4.52 Class ObAMResourceMgd

(Managed Code). An ObAMResourceMgd object represents a set of resources to which policy domains or policies apply. The resource set is selected by matching components of the Resource URL to ObAMResourceMgd members. For details on the object components, see "Class ObAMResourceMgd".

Managed Code

// Getters and setters
_property System::String *get_ResourceType();
_property System::String *get_HostID();
_property System::String *get_URLPrefix();
_property System::String *get_Description();
_property void set_IDFrom(ObAMResourceMgd *other);
_property void set_ResourceType(System::String *value);
_property void set_HostID(System::String *value);
_property void set_URLPrefix(System::String *value);
_property void set_Description(System::String *value);

5.4.53 Class ObAMTime

An object of the ObAMTime class represents a specific time. The ObAMTime class has one set method to set the hour, minutes and seconds. If the values provided are invalid, set will throw an ObAMException with the BAD_OBJECT code.

Label	Type	Range	Description
Hours (no key)	Integer Required	0 to 23	An integer representing the hour value in the object
Minutes	Integer Required	0 to 59	An integer representing the minutes value in the object
Seconds	Integer Required	0 to 59	An integer representing the seconds value in the object

Java

public int getHours();
  public int getMinutes();
  public int getSeconds();
  public void set(int hours, int minutes, int seconds)throws ObAMException;

5.4.54 Class ObAMTimeMgd

(Managed Code). An ObAMTimeMgd object represents a time. The ObAMTimeMgd class has one set method to set the hour, minutes and seconds. If the values provided are invalid, set will throw an ObAMException with the BAD_OBJECT code. For details on the object components, see "Class ObAMTime".

Label	Type	Range	Description
Hours (no key)	Integer Required	0 to 23	An integer representing the hour value in the object
Minutes	Integer Required	0 to 59	An integer representing the minutes value in the object
Seconds	Integer Required	0 to 59	An integer representing the seconds value in the object

Managed Code

// Getters and setters
_property int get_Hours();
_property int getMinutes();
_property int get_Seconds();
void set(int hours, int minutes, int seconds);

5.5 Test Objects

Test objects are objects that are used to provide input to and capture output from the ObAccessManager testAccess method. Because none of these objects is intended to be stored, they contain no key fields. This section describes the three test objects:

• Class ObAMAccessTest

• Class ObAMAccessTestResults

• Class ObAMAccessTestResult

5.5.1 Class ObAMAccessTest

An object of the ObAMAccessTest class represents a test of access policies. It specifies a resource and one or more users for whom access to the resource is to be tested.

The ObAMAccessTest object is the input argument to the ObAccessManager testAccess method, which returns an ObAMAccessTestResults object with the results of the access test.

Label	Type	Range	Description
URL (no key)	A string Required	Any	The URL (minus the resource type)
Resource	A string Required	Any	The resource type
Operation	An array At least one required	Any	The list of operations (defined by the resource type)
IPAddress	A string Optional	Any	An IP address
Date	One Date object Optional	See the class definition .	A date
Time	One Time object Optional	See the class definition .	A time
User	An array of Identity objects Optional	See the class definition .	An array of users. If omitted, access is tested for all users in the user directory
ShowAllowed	A Boolean flag, Required	0, meaning no, or other, meaning yes.	Specifies if the test should show users that are allowed accesses.
ShowDenied	A Boolean flag, Required	0, meaning no, or other, meaning yes.	Specifies if the test should show users that are denied accesses
ShowMatchingPolicy	A Boolean flag, Required	0, meaning no, or other, meaning yes.	Specifies if the test should show the policies that apply for each user
ShowMatchingExpr	A Boolean flag, Required	0, meaning no, or other, meaning yes.	Specifies if the test should show the authorization expression that applies for each user
ShowDeterminingRules	A Boolean flag, Required.	0, meaning no, or other, meaning yes.	Specifies if the test should show the authorization rules that were the determining rules of the authorization expression. For a description of determining rules, see "Class ObAMAuthorizationExpr".

Java

public String getURL(); 
  public String getResourceType(); 
  public String getIPaddress(); 
  public ObAMDate getDate(); 
  public ObAMTime getTime(); 
  int getNumberOfOperations(); 
  int getNumberOfUsers(); 
  String getOperation(int index);
  public boolean getShowMatchingPolicy(); 
  public boolean getShowMatchingExpr();
  public boolean getShowDeterminingRules();
  ObAMIdentity getUser(int index); 
  public boolean getShowAllowed(); 
  public boolean getShowDenied(); 
  public void setURL(String value); 
  public void setResourceType(String value); 
  public void addOperation(String value); 
  public void setIPaddress(String value); 
  public void setDate(ObAMDate value); 
  public void setTime(ObAMTime value); 
  public void addUser(ObAMIdentity value); 
  public void setShowAllowed(boolean value); 
  public void setShowDenied(boolean value); 
  public void setShowMatchingPolicy(boolean value);
  public void setShowMatchingExpr(boolean value);
  public void setShowDeterminingRules(boolean value);

Setting Up a Test Using Two Users

Example 5-8 shows an excerpt from a sample program. The code sets up a test to check authorization for two users, and it displays the results. The code uses an object of the ObAMAccessTest class to set up the test and an object of the ObAMAccessTestResults class for the results. See "Class ObAMAccessTestResults" for details. The code creates two ObAMIdentity objects, one for each user for whom authorization will be checked. It defines the policy to be used for the test, and it specifies the information to be returned for each user, including the result of evaluation of the authorization expression, whether authorization succeeded, failed, or whether a processing error occurred. For each user, it prints out the test information, including the determining rules that led up to the outcome of the expression result.Example 5-8 shows the code segment.

Example 5-8 Testing the System for Authorization Using Two Users

static void example5(ObAccessManager am) throws ObAMException
{                     .
                      .
 
        ObAMAccessTest test = new ObAMAccessTest();
        ObAMIdentity person1 = new ObAMIdentity();
        ObAMIdentity person2 = new ObAMIdentity();
 
        test.setResourceType("http");
        test.setURL("host1/myresources/doc1.html")
        test.addOperation("GET");
        test.addOperation("POST");
        test.setIPaddress(Ò192.168.1.14");
        ObAMDate date = new ObAMDate();
        ObAMTime time = new ObAMTime();
        date.set(2001, ObAMDate.NOVEMBER, 15);
        time.set(12, 0, 0);
        test.setDate(date);
        test.setTime(time);
 
        person1.setLoginID("A.Loomis");
        person2.setLoginID("J.Himes");
        person1.setLoginID("admin")
        test.addUser(person1);
        test.addUser(person2); 
 
        test.setShowAllowed(true);
        test.setShowDenied(true);
        test.setShowMatchingPolicy(true);
        test.setShowMatchingExpr(true);
        test.setShowDeterminingRules(true);
 
        ObAMAccessTestResults results = am.testAccess(test);
        System.out.println("Policy Domain : " + results.getPolicyDomain());
        for (int i = 0; i < results.getNumberOfResults(); i++) {
                 ObAMAccessTestResult result = results.getResult(i);
                 System.out.println("Result:");
                 System.out.println("User : " + result.getUser().getUID());
        if (result.getAuthorized() == true)                           
        {
              System.out.println("Authorized : ALLOWED");
        }
        else
        {
        if (result.getAuthorizationStatus() ==
                                ObAMAccessTestResult.DENIED)
                {
                      System.out.println("Authorized : DENIED");
                } 
        else if (result.getAuthorizationStatus() ==
                            ObAMAccessTestResult.INCONCLUSIVE)
                {
                      System.out.println("Authorized : INCONCLUSIVE");
                }
                else
                {
                      System.out.println("Authorized : ERROR");
        }
     }
                      System.out.println("Policy : " + result.getPolicy());
                      System.out.println(" Expr       : " + result.getExpr());
                      System.out.println(ÒDetermining Rules: ");
                for (int j=0; j<result.getNumberOfDeterminingRules(); j++)
           {
                      System.out.println(Ò Ò +result.getDeterminingRule(j)) ;
           }
                }
        }

5.5.2 Class ObAMAccessTestMgd

(Managed Code). An object of the ObAMAccessTestMgd class represents a test of access policies. It specifies a resource request and one or more users for whom access to the resource is to be tested. The ObAMAccessTestMgd object is the argument to the ObAccessManager testAccess method, which returns an ObAMAccessTestResultsMgd object with the results of the access test for each user. For details on the object components, see "Class ObAMAccessTest" .

Managed Code

// getters and setters
__property System::String *get_URL();
__property System::String *get_ResourceType();
__property System::String *get_IPaddress();
__property ObAMDateMgd *get_Date();
__property ObAMTimeMgd *get_Time();
__property int get_NumberOfOperations();
__property int get_NumberOfUsers();
System::String *getOperation(int index);
ObAMIdentityMgd *getUser(int index);
__property bool get_ShowAllowed();
__property bool get_ShowDenied();
__property bool get_ShowMatchingPolicy();
__property bool get_ShowMatchingExpr();
__property void set_URL(System::String *value);
__property void set_ResourceType(System::String *value);
__property void set_AddOperation(System::String *value);
__property void set_IPaddress(System::String *value);
__property void set_Date(ObAMDateMgd *date);
__property void set_Time(ObAMTimeMgd *time);
__property void set_AddUser(ObAMIdentityMgd *value);
__property void set_ShowAllowed(bool value);
__property void set_ShowDenied(bool value);
__property void set_ShowMatchingPolicy(bool value);
__property void set_ShowMatchingExpr(bool value);

5.5.3 Class ObAMAccessTestResults

An object of the ObAMAccessTestResults class contains the results of an access test. It includes an array of one or more AccessTestResult objects, described on"Class ObAMAccessTestResults" one for each user specified in the AccessTest.

Note: The trailing s in Results

Label	Type	Range	Description
PolicyDomain (no key)	A string Optional	Any	The name of the policy domain that includes the resources specified in the test.
Results	An array of AccessTestResult objects	See the class definition .	An array of results (AccessTestResult objects), one for each user specified in the test.

Java

public class ObAMAccessTestResults { 
  public String getPolicyDomain(); 
  public int getNumberOfResults(); 
  public ObAMAccessTestResult getResult(int index); 

C

typedef const void * ObAMAccessTestResults_t;
void ObAMAccessTestResults_delete(
                   ObAMAccessTestResults_t results);
const char *ObAMAccessTestResults_getPolicyDomain(
                   ObAMAccessTestResults_t results); 
int ObAMAccessTestResults_getNumberOfResults(
                   ObAMAccessTestResults_t results); 
ObAMAccessTestResult_t ObAMAccessTestResults_getResult(
                   ObAMAccessTestResults_t results, int index);

5.5.4 Class ObAMAccessTestResultsMgd

Managed Code. An ObAMAccessTestResultsMgd object contains the results of an access test.See "Class ObAMAccessTestResults". It includes an array of one or more AccessTestResultMgd objects, described on "Class ObAMAccessTestResultMgd", one for each user specified in the AccessTest.

Note: The trailing s in Results.

// getters and setters
__property System::String *get_PolicyDomain();
__property int get_NumberOfResults();
ObAMAccessTestResultMgd *getResult(int index);

5.5.5 Class ObAMAccessTestResult

An object of the ObAMAccessTestResult class contains the results of an access test, including the following information:

• The name of the policy, if any, that applies to the resource specified in the test.

• The identity of the user requesting the resource as a test case.

• The name of the authorization expression that applies to the user and the resource.

• The set of determining rules from the expression, if any, that determine the user's access rights and whether access to the resource is authorized for the user.

Label	Type	Range	Description
User (no key)	An Identity Object	See the class definition .	Information about the user.
Policy	A string Optional	Any	The name of the policy, if any, that applies to the user and the resource.
Authorization Expression	A string, Optional	Any See the class definition .	The name of the authorization expression that applies to the user and the requested resource.
Determining Rules	A string, Optional	Any See the class definition .	The set of one or more rules that contributed to the determination of the outcome of the authorization. These are the rules that determined the result of the authorization expression evaluation.
Authorized	A Boolean flag, Required	0, meaning no, or other, meaning yes.	Answers the question: Is access to the resource authorized for the user?

Note: No trailing s in Result.

Java

public ObAMIdentity getUser();
  public String getPolicy();
  public boolean getAuthorized();
  public String getExpr();
  public int getNumberOfDeterminingRules();
  public String getDeterminingRule (int index);
  public int getAuthorizationStatus();

5.5.6 Class ObAMAccessTestResultMgd

(Managed Code). An ObAMAccessTestResultMgd object contains the results of an access test for a single user. See "Class ObAMAccessTestResultsMgd" and "Class ObAMAccessTestResults". For details on the object components, see "Class ObAMAccessTestResult".

Note: No trailing s in Result.

5.5.7 Class ObAMException

The Policy Manager API Java methods throw exceptions of the class ObAMException when they detect problems with input data or with the connection to the Access Server.

Java

The Java ObAMException class extends the ObAccessException class as follows:

public static final int UNDEFINED = 400;
public static final int ADMIN_LOGIN_FAILED = 401;
public static final int NOT_AUTHORIZED = 402;
public static final int BAD_ARGUMENT = 403; 
public static final int EXISTING_OBJECT = 404; 
public static final int NO_OBJECT = 405; 
public static final int BAD_MESSAGE = 406; 
public static final int ALREADY_SET = 407; 
public static final int FINALIZED = 408; 
public static final int UNSUPPORTED_VERSION = 409; 
public static final int END_BEFORE_START = 410; 
public static final int NO_SET_ADMIN = 411; 
public static final int DATA_STORE_ERROR = 412;
public static final int INVALID_LDAP_FILTER = 413;
public static final int MISSING_REQUIRED_PARAM = 414;
public static final int INVALID_PARAM = 415;
public static final int NAME_REQUIRED = 416;
public static final int MODIFY_OBJECT_INVALID = 417;
public static final int INVALID_PROFILE_ATTRIBUTE = 418;
public static final int AUTHZ_SCHEME_CONFLICT = 419;
public static final int BAD_CHARACTER_DATA = 420;
public static final int CACHE_FLUSH_FAILED = 421;
public static final int AUTHN_SCHEME_PARAM = 422;
public static final int OBJECT_IN_USE = 423;
public static final int CANNOT_DELETE = 424;
public static final int POLICY_RESOURCE_TYPE_MISMATCH = 425;
public static final int INTERNAL_ERROR = 426;
public static final int INVALID_USER = 427;
public static final int INVALID_GROUP = 428;
public static final int FEATURE_NOT_SUPPORTED = 429;
public static final int INVALID_FAILURE_ACTION_ATTIBUTE = 430;
public static final int MISSING_AUTHN_STEP = 431;
public static final int INVALID_AUTHZ_EXPR_SYNTAX = 432;
public static final int AUTHZ_RULE_NOT_FOUND = 433;
public static final int AUTHN_SCHEME_DISABLED = 434;
public static final int INVALID_ACTION_TYPE = 435;
public static final int INVALID_DUPLICATE_ACTIONS_POLICY = 436;

5.5.8 Class ObAccessException

C

An ObAccessException object is thrown when the unexpected, unrecoverable problems occur. Because C does not provide an exception mechanism, the C binding includes methods to set up a handler to be called when an exception is thrown. The handler passes the exception, and it can extract the code and data from the exception. For C, the ObAccessExceptionClass is used. For details about the ObAccessException class, see "Class ObAccessException".

The following list of ObAccessException codes from the ObAccessException class is used.

ObAccessException_AM_UNKNOWN                     = 400,
ObAccessException_AM_ADMIN_LOGIN_FAILED,
ObAccessException_AM_NOT_AUTHORIZED,
ObAccessException_AM_BAD_ARGUMENT,
ObAccessException_AM_EXISTING_OBJECT,
ObAccessException_AM_NO_OBJECT,
ObAccessException_AM_BAD_MESSAGE,
ObAccessException_AM_GET_OBJECT_IN_SET,
ObAccessException_AM_FINALIZED,
ObAccessException_AM_UNSUPPORTED_VERSION,
ObAccessException_AM_END_BEFORE_START,
ObAccessException_AM_UNSUPPORTED_OPERATION,
ObAccessException_AM_NO_SET_ADMIN,
ObAccessException_AM_DATA_STORE_ERROR,
ObAccessException_AM_READ_DATA_STORE_ERROR,
ObAccessException_AM_INVALID_LDAP_FILTER,
ObAccessException_AM_MISSING_REQUIRED_PARAM,
ObAccessException_AM_INVALID_PARAM,
ObAccessException_AM_NAME_REQUIRED,
ObAccessException_AM_MODIFY_OBJECT_INVALID,
ObAccessException_AM_INVALID_PROFILE_ATTRIBUTE,
ObAccessException_AM_AUTHZ_SCHEME_CONFLICT,
ObAccessException_AM_BAD_CHARACTER_DATA,
ObAccessException_AM_CACHE_FLUSH_FAILED,
ObAccessException_AM_AUTHN_SCHEME_PARAM,
ObAccessException_AM_OBJECT_IN_USE,
ObAccessException_AM_CANNOT_DELETE,
ObAccessException_AM_POLICY_RESOURCE_TYPE_MISMATCH,
ObAccessException_AM_INTERNAL_ERROR,
ObAccessException_AM_INVALID_USER,
ObAccessException_AM_INVALID_GROUP,
ObAccessException_AM_FEATURE_NOT_SUPPORTED,
ObAccessException_AM_INVALID_FEATURE_ACTION_ATTRIBUTE

typedef void (*ObAccessExceptionHandler2_t)
                        (ObAccessException_t e);
void ObAccessException_setHandler2(
                        ObAccessExceptionHandler2_t handler);
ObAccessExceptionCode_t ObAccessException_getCode(
                        ObAccessException_t e);
const char *ObAccessException_getParameter(
                        ObAccessException_t e, int which);
const char *ObAccessException_toString(ObAccessException_t e);

5.5.9 Class ObAccessExceptionMgd

Managed Code

When the Policy Manager API methods for managed code detect problems, they throw an ObAccessExceptionMgd exception. For enumeration and description of the constants that define the exception codes returned for errors encountered, see "C-Family Status and Error Message Strings". For a complete description of the class, see "ObAccessException".

public:
  ObAccessExceptionMgd: public System::Exception {
  ObAccessExceptionMgd(ObAccessException *ex);
  System::String *getParameter(int index);
  System::String *getCodeString(ObAccessExceptionCode_t code);
  __property System::String *get_String(); };

5.6 Sample Program

The following listing is part of a sample program that is installed with the software in the Identity_install_dir/identity/oblix/access_server_sdk/samples folder. The sample program uses many of the Policy Manager API classes. Code listings shown throughout this chapter are excerpted from the sample program.

This portion of the sample program creates a policy domain called My Domain for resources in http://host1/myresources. Here are some of the tasks the code in Example 5-9 performs:

• The program sets the default authentication rule for My Domain to use the Oracle Access and Identity authentication scheme.

• It sets the default audit rule for the policy domain to audit authentication successes, authentication failures, and authorization failures. For these events, it specifies that the user's uid and cn attributes are to be logged.

• It creates an authorization rule that enables J. Smith, J. Himes, and anyone in group1, access to the protected resources. On successful authorization, the rule returns a header variable userId that is set to the user's uid attribute.

• The application creates a second authorization rule with access conditions which include timing conditions and an IP address requirement. This rule gives anyone access after 12:00:00 of October 15, 2001 on the 1st, 2nd, and 30th of January and November if the day is either a Monday or a Tuesday and the user's browser has an IP address of 192.168.*.*.

• The code adds an action to the second rule that the rule returns on successful authorization.

• The code creates a third authorization rule that enables anyone access to the protected resources.

• The code creates a default authorization expression for the policy domain and it sets the duplicate actions policy to Overwrite. It adds an action to be returned if the authorization expression is evaluated to a result of Inconclusive.

• It sets up two policies within the policy domain.

• It creates an administrator rule to assign delegate administrator rights for the policy domain to J. Smith.

• The code creates the My Domain policy domain. If the policy domain exists, the code throws an exception.

• It gets and displays the names of all policy domains that begin with My. If the code successfully created the new policy domain, the list will include the My Domain policy domain.

Example 5-9 Sample Program for Creating a Policy Domain

domain.setName("My Domain");
                  domain.setDescription("excerpted from the sample program");
                  domain.setEnabled(true);
                  ObAMResource resource = new ObAMResource();
                  resource.setResourceType("http");
                  resource.setHostID("host1");
                  resource.setURLPrefix("/myresources");
                  domain.addResource(resource);
 
// Set the default authentication rule 
 
            ObAMAuthenticationRule authnRule = new ObAMAuthenticationRule();
            authnRule.setScheme("Oracle Access and Identity");
            domain.setDefaultAuthenticationRule(authnRule);
            
// Set the default audit rule 
 
            ObAMAuditRule auditRule = new ObAMAuditRule();
            auditRule.addEvent(ObAMAuditRule.AUTHENTICATION_SUCCESS);
            auditRule.addEvent(ObAMAuditRule.AUTHENTICATION_FAILURE);
            auditRule.addEvent(ObAMAuditRule.AUTHORIZATION_FAILURE);
             auditRule.addAttribute("uid");
            auditRule.addAttribute("cn");
            domain.setDefaultAuditRule(auditRule);
 
// Create an authorization rule
 
           ObAMAuthorizationRule authzRule1 = new ObAMAuthorizationRule();
            authzRule1.setName("Authz Rule 1");
            authzRule1.setEnabled(true);
            ObAMAccessConditions access1 = new ObAMAccessConditions();
            ObAMIdentity person1 = new ObAMIdentity();
 
           person1.setLoginID("J.Smith");
            access1.addPerson(person1);
            ObAMIdentity person2 = new ObAMIdentity();
            person2.setLoginID("J.Himes");
            access1.addPerson(person2);
            ObAMIdentity group = new ObAMIdentity();
            group.setName("group1");
            access1.addGroup(group);
            person1.setLoginID("admin");
            access1.addPerson(person1);
            authzRule1.setAllowAccessConditions(access1);
 
// Add a success action to the authorization rule
            
            ObAMAction action1 = new ObAMAction();
            action1.setType("headerVar");
            action1.setName("UserIs");
            action1.setValue("uid");action1.setValueType(ObAMAction.ATTRIBUTE);
            authzRule1.addActionOfType(ObAMObjectWithActions.SUCCESS, action1);
 
/ Add the authorization rule to the policy domain 
 
            domain.addAuthorizationRule(authzRule1); 
 
 
// Create a second authorization rule
 
            ObAMAuthorizationRule authzRule2 = new ObAMAuthorizationRule();
                  authzRule2.setName("Authz Rule 2");
                  authzRule2.setEnabled(true);
                  authzRule2.setName("Authz Rule 2");
                  authzRule2.setEnabled(true);
                  ObAMTimingConditions timing2 = new ObAMTimingConditions();
                  ObAMDate startDate = new ObAMDate();
                  ObAMTime startTime = new ObAMTime();
                  startDate.set(2001, ObAMDate.OCTOBER, 31);
                  startTime.set(12, 0, 0);
                  timing2.setRelativeTo(ObAMTimingConditions.LOCAL_TIME);
                  timing2.setStartDate(startDate);
                  timing2.setStartTime(startTime);
                  timing2.addMonth(ObAMDate.JANUARY);
                  timing2.addMonth(ObAMDate.NOVEMBER);
                  timing2.addDayOfMonth(1);
                  timing2.addDayOfMonth(2);
                  timing2.addDayOfMonth(30);
                  timing2.addDayOfWeek(ObAMDate.MONDAY);
                  timing2.addDayOfWeek(ObAMDate.TUESDAY);
                  authzRule2.setTimingConditions(timing2);
                  ObAMAccessConditions access2 = new ObAMAccessConditions();
                  access2.addIPAddress("192.168.*.*");
                  authzRule2.setAllowAccessConditions(access2);
 
// Add a failure action to the second authorization rule
            ObAMAction action2 = new ObAMAction();
                  action2.setType("otherType");
                  action2.setName("authzAction");
                  action2.setValue("b");
                  action2.setValueType(ObAMAction.FIXEDVALUE); 
                  authzRule2.addActionOfType(
                                                                  ObAMObjectWithActions.FAILURE, action2);
 
// Add the rule to the domain
        domain.addAuthorizationRule(authzRule2);
 
// Create a third authorization rule to allow anyone access
                  ObAMAuthorizationRule authzRule3 = new ObAMAuthorizationRule();
                  authzRule3.setName("Authz Rule 1");
                  authzRule3.setEnabled(true);
                  ObAMAccessConditions access3 = new ObAMAccessConditions();
                  access3.addRole("Anyone");
                  authzRule3.setAllowAccessConditions(access3);
 
// Add the rule to the domain
                  domain.addAuthorizationRule(authzRule3);
 
/ Create a fourth authorization rule to deny anyone access
 
                 ObAMAuthorizationRule authzRule4 = new ObAMAuthorizationRule();
                  authzRule4.setName("Authz Rule 2");
                  authzRule4.setEnabled(true);
                  ObAMAccessConditions access4 = new ObAMAccessConditions();
                  access4.addRole("Anyone");
                  authzRule4.setDenyAccessConditions(access4);
 
// Add the rule to the domain                  
                  
                  domain.addAuthorizationRule(authzRule4);
 
// Create a default authorization expression for the policy domain
                  ObAMAuthorizationExpr pd_expr = new ObAMAuthorizationExpr();
                  pd_expr.setExpression("Authz Rule 1 & Authz Rule 2");
                  pd_expr.setDuplicateActionsPolicy(
                                          ObAMAuthorizationExpr.ACTION_OVERWRITE);
// Add an Inconclusive action
                  ObAMAction action3 = new ObAMAction();
                  action3.setType("otherType");
                  action3.setName("authzAction");
                  action3.setValue("a");
                  action3.setValueType(ObAMAction.FIXEDVALUE);
                  pd_expr.addActionOfType(ObAMObjectWithActions.INCONCLUSIVE, action3); 
 
// Add the expression to the policy domain
                  domain.setDefaultAuthorizationExpr(pd_expr);
 
// Set policy 1 for My Domain for GET
// and POST to http://host1/myresources/doc1.html
 
            ObAMPolicy policy1 = new ObAMPolicy();
            policy1.setName("My Domain Policy 1");
            policy1.setResourceType("http");
            policy1.setHostID("host1");
            policy1.setURLPattern("/myresources/doc1.html");
            policy1.addOperation("GET");
            policy1.addOperation("POST");
            policy1.addResource(resource);
            ObAMAuthorizationExpr p1_authzExpr = new ObAMAuthorizationExpr();
            p1_authzExpr.setExpression("Authz Rule 1 & Authz Rule 2");
            p1_authzExpr.setDuplicateActionsPolicy(ObAMAuthorizationExpr.UNDEFINED);
            policy1.setAuthorizationExpr(p1_authzExpr);
            domain.addPolicy(policy1);
 
/ Set policy 2 for My Domain for GET 
// and POST to http://host1/myresources/prog
// with a query string or post data of progid=1. 
            ObAMPolicy policy2 = new ObAMPolicy();
            policy2.setName("My Domain Policy 2");
            policy2.setResourceType("http");
            policy2.setURLPattern("/myresources/prog");
            policy2.addOperation("GET");
            policy2.addOperation("POST");
            policy2.addResource(resource);
            ObAMAuthorizationExpr p2_authzExpr = new ObAMAuthorizationExpr();
            p2_authzExpr.setExpression("Authz Rule 1 & Authz Rule 2");
            p2_authzExpr.setDuplicateActionsPolicy(
                                 ObAMAuthorizationExpr.ACTION_IGNORE);
            policy2.setAuthorizationExpr(p2_authzExpr);
            ObAMParameter parameter2 = new ObAMParameter();
            parameter2.setName("progid");
            parameter2.setValue("1");
            policy2.addParameter(parameter2);
            domain.addPolicy(policy2);
// Set an admin rule for My Domain that gives delegate
// rights to J.Smith
 
      ObAMAdminRule adminRule = new ObAMAdminRule();
      ObAMIdentity adminPerson = new ObAMIdentity();
      adminPerson.setLoginID("J.Smith"); 
 
     adminPerson.setLoginID("admin");
      adminRule.addPerson(adminPerson);
      domain.setDelegateAdminRule(adminRule);
 
/ Create My Domain. If it already exists, this will throw an exception.
            
      am.setPolicyDomain(domain, ObAccessManager.CREATE);
// Get and display all domains that start with My
            ObAMPolicyDomain[] domains =
                                 am.getPolicyDomains(ObAccessManager.MAX,
            "My", ObAccessManager.BEGINS_WITH);
                  if (domains != null) {
                        for (int i = 0; i < domains.length; i++) {
                                      displayPolicyDomain(0, "Policy Domain:", domains[i]);
                        }
                  };
            }