Fetching Attributes in J2EE Agents (Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents)

Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents

Fetching Attributes in J2EE Agents

Certain applications rely on the presence of user-specific profile information in some form in order to process the user requests appropriately. J2EE agents provide the functionality that can help such applications by making these attributes from the user's profile available in various forms. Policy Agent 3.0 allows the following attribute types to be fetched using the corresponding properties:

Profile Attributes: Profile Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.agents.config.profile.attribute.fetch.mode)
Session Attributes: Session Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.agents.config.session.attribute.fetch.mode)
Policy Response Attributes: Response Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.agents.config.response.attribute.fetch.mode)

The following values are possible for these three properties:

NONE
HTTP_HEADER
REQUEST_ATTRIBUTE
HTTP_COOKIE

The default value for these properties is NONE, which specifies that that particular attribute type (profile attribute, session attribute, or policy response attribute) is not fetched. The other possible values (HTTP_HEADER, REQUEST_ATTRIBUTE, or HTTP_COOKIE) that can be used with these properties specify which method will be used to fetch a given attribute type. For more information, see Methods for Fetching Attributes in J2EE Agents.

Depending upon how these values are set, the agent retrieves the necessary attributes available for the logged on user and makes them available to the application.

The final subsection in this section describes other J2EE agent properties that can influence the attribute fetching process, see Common Attribute Fetch Processing Related Properties.

The following subsections provide information about how to set the type of attribute that is fetched.

Fetching Profile Attributes in J2EE Agents

To obtain user-specific information by fetching profile attributes, assign a mode to the profile attribute property and map the profile attributes to be populated under specific names for the currently authenticated user. The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching profile attributes and then demonstrates a way to map those attributes:

Example:

In OpenSSO Enterprise Console, Select the REQUEST_ATTRIBUTE mode option of the Profile Attribute Fetch Mode property (Tab: Application, Name: com.sun.identity.agents.config.profile.attribute.fetch.mode).

Then, map profile attributes using the property labeled Profile Attribute Mapping (Tab: Application, Name: com.sun.identity.agents.config.profile.attribute.mapping), such as illustrated in the following example:

Map Key: cn
Corresponding Map Value: CUSTOM-Common-Name

Map Key: mail
Corresponding Map Value: CUSTOM-Email

When you are done setting the Profile Attribute Mapping property as described in this example, it appears in OpenSSO Enterprise Console with the following format:

[cn]=CUSTOM-Common-Name
[mail]=CUSTOM-Email

Fetching Session Attributes in J2EE Agents

To obtain user-specific information by fetching profile attributes, assign a mode to the session attribute property and map the session attributes to be populated under specific names for the currently authenticated user. The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching session attributes and then demonstrates a way to map those attributes:

Example:

In OpenSSO Enterprise Console, Select the REQUEST_ATTRIBUTE mode option of the Session Attribute Fetch Mode property (Tab: Application, Name: com.sun.identity.agents.config.session.attribute.fetch.mode).

Then, map session attributes using the property labeled Session Attribute Mapping (Tab: Application, Name: com.sun.identity.agents.config.session.attribute.mapping), such as illustrated in the following example:

Map Key: UserToken
Corresponding Map Value: CUSTOM-userid

When you are done setting the Session Attribute Mapping property as described in this example, it appears in OpenSSO Enterprise Console with the following format:

[UserToken]=CUSTOM-userid

Fetching Policy Response Attributes in J2EE Agents

To obtain user-specific information by fetching policy response attributes, assign a mode to the policy response attribute property and map the policy response attributes to be populated under specific names for the currently authenticated user. The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching policy response attributes and then demonstrates a way to map those attributes:

Example:

In OpenSSO Enterprise Console, Select the REQUEST_ATTRIBUTE mode option of the Response Attribute Fetch Mode property (Tab: Application, Name: com.sun.identity.agents.config.response.attribute.fetch.mode).

Then, map response attributes using the property labeled Response Attribute Mapping (Tab: Application, Name: com.sun.identity.agents.config.response.attribute.mapping), such as illustrated in the following example:

Map Key: cn
Corresponding Map Value: COMMON_NAME

Map Key: mail
Corresponding Map Value: CUSTOM-EMAIL_ADDR

When you are done setting the Profile Attribute Mapping property as described in this example, it appears in OpenSSO Enterprise Console with the following format:

[cn]=COMMON_NAME
[mail]=CUSTOM-EMAIL_ADDR

With this property, you can specify any number of attributes that are required by the protected application. For the preceding example, the application requires the attributes cn and mail and searches for these attributes under the names COMMON_NAME and EMAIL_ADDR.

Methods for Fetching Attributes in J2EE Agents

The attribute types can be fetched by different methods as follows:

HTTP Headers
Request Attributes
Cookies

Fetching Attributes as HTTP Headers

When the agent is configured to provide the LDAP attributes as HTTP headers, these attributes can be retrieved using the following methods on the javax.servlet.http.HttpServletRequest interface:

long getDateHeader(java.lang.String name)

java.lang.String getHeader(java.lang.String name)

java.util.Enumeration getHeaderNames()

java.util.Enumeration getHeaders(java.lang.String name)

int getIntHeader(java.lang.String name)

The property labeled Fetch Attribute Date Format (Tab: Application, Name: com.sun.identity.agents.config.attribute.date.format) controls the parsing of a date value from an appropriate string as set in the LDAP attribute.

This property defaults to the value EEE, d MMM yyyy hh:mm:ss z and should be changed as necessary.

Multi-valued attributes can be retrieved as an instance of java.util.Enumeration from the following method:

java.util.Enumeration getHeaders(java.lang.String name)

Fetching Attributes as Request Attributes

When the agent is configured to provide the LDAP attributes as request attributes, the agent populates these attribute values into HttpServletRequest as attributes that can later be used by the application as necessary. These attributes are populated as java.util.Set objects, which must be cast to this type before they can be successfully used.

Fetching Attributes as Cookies

When the agent is configured to provide the LDAP attributes as cookies, the necessary values are set as server specific cookies by the agent with the path specified as “/.”

Multi-valued attributes are set as a single cookie value in a manner that all values of the attribute are concatenated into a single string using a separator character that can be specified by the property labeled Cookie Separator Character property (Tab: Application, Name: com.sun.identity.agents.config.attribute.cookie.separator).

One of the tasks of the application is to parse this value back into the individual values to ensure the correct interpretation of the multi-valued LDAP attributes for the logged on user.

When you are fetching attributes as cookies, also use the cookie reset functionality to ensure that these cookies get cleaned up from the client browser when the client browser’s session expires. For more information, see Using Cookie Reset Functionality in J2EE Agents.

Common Attribute Fetch Processing Related Properties

This section lists the most common configuration properties that are used to influence attribute fetching.

Cookie Separator Character property (Tab: Application, Name: com.sun.identity.agents.config.attribute.cookie.separator)

This property allows you to assign a character to be used to separate multiple values of the same attribute when it is being set as a cookie. The value that you assign to this property is the character, for example the pipe symbol “|”, that will separate multiple values of the same attribute when it is being set as a cookie.

Attribute Cookie Encode property (Tab: Application, Name: com.sun.identity.agents.config.attribute.cookie.encode)

This property is a flag (enabled or not enabled) that indicates if the value of the attribute should be URL encoded before being set as a cookie.

Fetch Attribute Date Format (Tab: Application, Name: com.sun.identity.agents.config.attribute.date.format)

This property allows you to set the format of date attribute values to be used when the attribute is set to HTTP header. This format is based on the definition as provided in java.text.SimpleDateFormat. The format for the value of this property is as follows:

EEE, d MMM yyyy hh:mm:ss z