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 2.2 allows the following attribute types to be fetched using the corresponding property from the J2EE agent AMAgent.properties configuration file:

Profile Attributes

com.sun.identity.agents.config.profile.attribute.fetch.mode

Session Attributes

com.sun.identity.agents.config.session.attribute.fetch.mode

Policy Response Attributes

com.sun.identity.agents.config.response.attribute.fetch.mode

The following values are possible for these three properties:

• NONE

• HEADER

• REQUEST_ATTRIBUTE

• 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 (HEADER, REQUEST_ATTRIBUTE, or 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 properties in the J2EE agent AMAgent.properties configuration file 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:

Assigning a Mode to Profile Attributes

com.sun.identity.agents.config.profile.attribute.fetch.mode = REQUEST_ATTRIBUTE

The key is the profile attribute name and the value is the name under which that attribute will be made available.

Mapping Profile Attributes

com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM- Common-Name com.sun.identity.agents.config.profile.attribute.mapping[mail]=CUSTOM- Email com.sun.identity.agents.config.profile.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.profile.attribute.mapping[] =

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:

Assigning a Mode to Session Attributes

com.sun.identity.agents.config.session.attribute.fetch.mode = REQUEST_ATTRIBUTE

The key is the session attribute name and the value is the name under which that attribute will be made available.

Mapping Session Attributes

com.sun.identity.agents.config.session.attribute.mapping[UserToken]= CUSTOM-userid com.sun.identity.agents.config.session.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.session.attribute.mapping[] =

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:

Assigning a Mode to Policy Response Attributes

com.sun.identity.agents.config.response.attribute.fetch.mode = REQUEST_ATTRIBUTE

The key is the policy response attribute name and the value is the name under which that attribute will be made available.

Mapping Policy Response Attributes

com.sun.identity.agents.config.response.attribute.mapping com.sun.identity.agents.config.response.attribute.fetch.mode = REQUEST_ATTRIBUTE com.sun.identity.agents.config.response.attribute.mapping[] =

Using this property for mapping policy response attributes, you can specify any number of attributes that are required by the protected application. For example, if the application requires the attributes cn and mail, and it expects these attributes to be available under the names COMMON_NAME and EMAIL_ADDR, then the configuration setting would be as follows:

com.sun.identity.agents.config.response.attribute.mapping[cn] = COMMON_NAME

com.sun.identity.agents.config.response.attribute.mapping[mail] = 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 that controls the parsing of a date value from an appropriate string as set in the LDAP attribute is the following:

com.sun.identity.agents.config.attribute.date.format

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 the 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 following configuration entry:

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.

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. This property is set in the following manner:

com.sun.identity.agents.config.attribute.cookie.separator = |

com.sun.identity.agents.config.attribute.cookie.encode

This property is a flag that indicates if the value of the attribute should be URL encoded before being set as a cookie. This property is set in the following manner:

com.sun.identity.agents.config.attribute.cookie.encode = true

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. This property is set in the following manner:

com.sun.identity.agents.config.attribute.date.format = EEE, d MMM yyyy hh:mm:ss z