Chapter 3   Profile and Policy API




Profile and Policy API Overview

---

The Profile and Policy Application Programming Interface (API) provides developers of iPlanet Portal Server client software a mechanism to manage user and role profiles. It also allows application programmers to perform policy checks on the user before granting any permission. Additional, the iPlanet Portal Server Administration console relies on the Profile and Policy API to manage users and roles.

Additionally, the Profile and Policy API provides an XML DTD to define the format for data streams to provide to the server profile process and to define the format for data streams coming from the server profile process. These formats are required to access profile and policy functions from non-Java client software, but can be transparently integrated into Java applications, as shown in the sample code in this chapter.

Profile and Policy API Functionality

---

The Profile and Policy API performs a variety of profiling and access control tasks within the iPlanet Portal Server environment, including:

• Returning any or all attributes and values to the calling application

• Uses the policy methods to check user access privilege before granting any permission

All of the main entities controlled by the Profile and Policy API (users, roles, and domains) are organized in a tree structure, as shown in Figure 3-1. Each entity inherits attributes from its parent and separately maintains its own attributes, which override inherited attributes.

Figure 3-1    The Profile and Policy API Organization Structure

Profile and Policy attributes are stored in the form of name-value pairs in profile database. Access privileges are special attributes stored in the Profile and Policy database. Boolean type privileges have a boolean value of true or false. List type privileges have an allow value list and a deny value list.

The policy for a domain, role or user is implemented by setting the privileges for an individual domain, role, or user profile.

Implementing the Profile and Policy API

---

As with the other APIs, implementing an iPlanet Portal Server client application in Java is substantially less complex than implementing in any other language, simply because referencing existing iPlanet Portal Server classes masks much of the communication and protocol manipulation. Therefore, only be concerned with the Profile attributes and values wanting to create, write to, read from, or otherwise manipulate, and can ignore the communication protocols involved for all Java client implementations.

Profile and Policy API Classes and Interfaces

The Profile and Policy API provides the following Java classes and interfaces:

• Profile Class provides the following methods:
  • Profile methods provides common methods to create, delete, and access profile attributes

  • Policy methods provides methods to check access privileges

• ProfileEvent Class represents profile event notification. This notification is generated when profile attribute, or privilege is changed

• Profile Exception Class is a generic profile service exception For simplicity this profile API throws this exception with a specified exception type. See Appendix C, "iPlanet Portal Server API Exceptions"

• Profile Listener (Interface) This interface needs to be implemented by the applications in order to receive profile events

Specific implementation details are contained in the Profile and Policy API Javadocs, available online at:

http://yourserver:port/docs/en_US/javadocs

The following section outlines the procedures for using the Profile and Policy API methods and classes.

Interactions, Assumptions, and Dependencies

The Profile and Policy API uses:

• The Session API to validate the user session

• Platform low level API for over the wire communication

See Appendix A for more information about direct communication with the profile server process.

Additionally, it is assumed that applications supply lists of profile attributes, access privileges, and their initial values.

Exception Handling

The Profile and Policy API performs a wide range of checks and throws exceptions in the following cases. See Appendix C, "iPlanet Portal Server API Exceptions" for all the Profile API exceptions.

• Requested profile is not found

• Failure of store operation

• User does not have permission to do requested operation on an attribute

• Requested attribute is not found in user profile

• User session is not valid/inactive

• Privilege not found in user profile

• Invalid value supplied for attribute

• Illegal privilege name

• Illegal attribute name

• Illegal wild character expression

• Illegal wildcard expression

• Illegal match value

Using the Profile and Policy API

---

The Profile and Policy API provides methods to add and delete roles to the permission lists.

Each attribute defined in the Profile database has its own qualifiers, including:

• Read/Write permission Lists

• Remote flag

Read/Write permission Lists tell which role can perform read/write operations on an attribute.

Getting Profile Object

For example, an application programmer could get a profile object with the Session API, as follows:

Profile p = session.getUserprofile () ;

Getting Attribute Values

An application programmer could get a profile attribute with the Profile and Policy API, as follows:

string name = p.getAttributeString ("HelloServlet-color") ;

• Returns HelloServlet-color attribute value

Setting Attribute Values

For example, an application programmer could set a profile attribute with the Profile and Policy API, as follows:

p.getAttributeString ("HelloServlet-color","blue",Profile.NEW) ;

• Sets HelloServlet-color to blue

Checking Policy (Using Boolean Privileges)

For example, an application programmer could check policy with the Profile and Policy API, as follows:

p.isAllowed("HelloServlet-execute")

• Returns true if HelloServlet-execute is set to true

• Returns false if HelloServlet-execute is set to false

Checking Policy (Using List Privileges)

For example, an application programmer could set and check policy with the Profile and Policy API, as follows:

p.isAllowed("HelloServlet-changeColor",session.getClientDomain() ,Profile.Regular

• Returns true if user domain is in allow list and not in deny list

• Returns true if allow list contains '*' and user domain is not in deny list

• Returns false if user domain is in deny list

• Returns false if user domain is not in deny list or allow list

Refer to Code Example 3-2 for a sample Profile API.

Import the iPlanet Portal Server Classes

At a minimum, the Java client application should import the iPlanet Portal Server Profile, and Session classes, as shown here.

Code Example 3-1 Importing iPlanet Portal Server Classes

---

import java.io.*; import java.util.*; import java.net.*; import com.iplanet.portalserver.naming.*; import com.iplanet.portalserver.session.*; import com.iplanet.portalserver.profile.*;

Sample Code

The following code sample illustrates how a new application might use the Profile API. This code segment uses the Session object to get the user profile, which will then check a privilege. If the provider does not throw an exception, an attribute is returned.

Code Example 3-2 Sample Profile API 

---

public class HelloServlet extends HttpServlet {

public void doGet(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException {

try {

// Get a session as described in the previous sample : sess

// Get user profile name from the session object

Profile p = s.getUserProfile();

// Get a profile attributes

String color = p.getAttributeString("HelloServlet-color");

String name = p.getAttributeString("HelloServlet-name");

// Add a profile listener

p.addProfileListener(new HelloProfileListener());

// Get policy information

if (p.isAllowed("HelloServlet-execute")) {

System.out.println("User is allowed to execute this program");

}

// The HelloServlet-changeColor is defined as a list type privilege.

// What's in the list is domains. If the user domain is in the

// privilege HelloServlet-changeColor's allow list, ths user is allowed

// to change color. Otherwise, the user is denied to change color.

if (p.isAllowed("HelloServlet-changeColor", s.getClientDomain(), Profile.REGULAR)) {

System.out.println("User is allowed to change color");

}

} catch (ProfileException e) {

}

}

public class HelloProfileListener implements ProfileListener {

public void profileChanged(ProfileEvent notify){

Profile p = notify.getProfile();

int type = notify.getType();

// Either the color or the name attribute may have changed

// Get the new values for these attributes.

if (type == ProfileEvent.PROFILE_CHANGE) {

try {

String color = p.getAttributeString("HelloServlet-color");

String name = p.getAttributeString("HelloServlet-name");

} catch (ProfileException pe) {

System.out.println("Profile: getAttribute() failed");

}

return;

} else {

// no attributes were changed

// profiles were created or deleted

return;

}

}

}

}