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

Chapter 4 Common J2EE Agent Tasks and Features in Policy Agent 3.0

After installing the J2EE agent and performing the required post-installation steps, you must adjust the agent configuration to your site's specific deployment. This chapter describes how to modify J2EE agents generally. Therefore, the information in this chapter tends to apply to all J2EE agents in the Policy Agent 3.0 software set.

This chapter focuses on methods available for managing this J2EE agent, specifying the features you can configure and the tasks you can perform using each method as follows:

Common J2EE Agent Tasks and Features

This section focuses on features that involve setting J2EE agent property values. Assigning values to properties is the key method available for configuring agent features. The topics described in this section are typically those of greatest interest in real-world deployment scenarios. This section does not cover every property. For a description of all the agent properties, see the following link: http://wikis.sun.com/display/OpenSSO/agent3properties

The manner in which these properties are set varies depending on if the agent configuration is centralized on the OpenSSO Enterprise server or contained locally with the agent. However, regardless of if the agent configuration is local or centralized, a small subset of properties is always stored locally with the agent in the OpenSSOAgentBootstrap.properties file. The properties in the bootstrap file are required for the agent to start up and initialize itself. For example, the agent profile name and password used to access the OpenSSO Enterprise server are stored in this bootstrap file. To change the values in the bootstrap file, you must edit the file directly. For information about the ssoadm utility, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

In terms of the properties not stored in the OpenSSOAgentBootstrap.properties file and when the J2EE agent configuration is centralized on the OpenSSO Enterprise server, you can use the OpenSSO Enterprise Console or the ssoadm command-line utility to set the J2EE agent properties.

When the J2EE agent configuration is local, OpenSSO Enterprise Console and the ssoadm utility tool are not available for agent configuration. Instead, you must configure the majority of J2EE agent properties using the OpenSSOAgentConfiguration.properties file. However, the properties in the bootstrap file still apply in a local configuration. In all situations, you must edit the properties in the bootstrap file directly.


Caution – Caution –

The content of the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file are very sensitive. Changes made can result in changes in how the agent works. Errors made can cause the agent to malfunction.


The following is the location of the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file:

PolicyAgent-base/AgentInstance-Dir/config

For more information about the Policy Agent 3.0 directory structure, see J2EE Agent Directory Structure in Policy Agent 3.0.

The following topics are discussed in this section:

How J2EE Agent Properties Are Discussed in this Guide

When this guide discusses editing a property, the emphasis is on the property as set in OpenSSO Enterprise Console. For a description of how to access the J2EE agent properties using OpenSSO Enterprise Console, see To Navigate in OpenSSO Enterprise 8.0 Console to the J2EE Agent Properties.

To set a property in OpenSSO Enterprise Console, the name of the Console tab in which the property is located is useful as well as the property label. The property name is not usually as important when using OpenSSO Enterprise Console, but can still be of some use and is therefore included in this guide whenever a property is mentioned.


Example 4–1 The Method Used for Discussing J2EE Agent Properties in This Guide

Most agent properties mentioned in this guide are presented using a format that is most useful for those configuring properties using OpenSSO Enterprise Console. However, that format is not used when the property is in the OpenSSOAgentBootstrap.properties file since the bootstrap file is not accessible using OpenSSO Enterprise Console. The following example illustrates the format usually used in this guide to mention an agent property:

Example: The property labeled Login Form URI (Tab: Application, Name: com.sun.identity.agents.config.login.form).



Caution – Caution –

Every time you change a property using OpenSSO Enterprise Console, you must click Save on that page for the change to take place. Furthermore, if the property is not hot-swappable, you must restart the Policy Agent container for the new value to take effect.


The above example provides the following details about the property:

Property label used in OpenSSO Enterprise Console:

Login Form URI

The OpenSSO Enterprise Console tab within which the property is located:

Application

The property name:

com.sun.identity.agents.config.login.form

Since the emphasis of this guide is on the use of OpenSSO Enterprise Console, other methods of editing properties are not as consistently mentioned. If you are configuring agent properties using the ssoadm utility, the explanations provided in this guide about the purpose of the agent properties are still applicable, however for details on configuring the agent properties using the ssoadm utility, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

If the agent is configured locally, therefore using the OpenSSOAgentConfiguration.properties file, you cannot use OpenSSO Enterprise Console. For such a scenario, descriptions of the properties provided in this guide are still applicable and some limited information about setting the property in the OpenSSOAgentConfiguration.properties file is provided. However. for the most part, you should consult the OpenSSOAgentConfiguration.properties file itself for information about setting the properties.

Hot-Swap Mechanism in J2EE Agents

Most J2EE agent properties are hot-swap enabled. Properties are identified as hot-swappable or not in OpenSSO Enterprise Console (a centralized agent configuration option) and in the OpenSSOAgentConfiguration.properties file (the local agent configuration option). When changes are made to the agent configuration, the changes must be communicated to the property configuration cache for it to be updated. Hot-swap enabled (or Hot-swappable) properties allow such changes to be made without having to restart the agent server. For properties that are not hot-swappable, the new values are only picked up by the agent once the agent container is restarted.

Therefore, when hot-swappable properties are changed on the OpenSSO Enterprise server (using OpenSSO Enterprise Console or the ssoadm utility), the changes can be communicated using notifications or polling. However, when the agent configuration is stored with the agent locally (in the OpenSSOAgentConfiguration.properties), changes to the property values can only be communicated through polling. The communication of property value changes results in an update to the property configuration cache.

For notifications, the property that controls the hot-swap mechanism is labeled Agent Configuration Change Notification (Tab: Global, Name: com.sun.identity.agents.config.change.notification.enable) and for polling, the property that controls the hot-swap mechanism is labeled Configuration Reload Interval (Tab: Global, Name: com.sun.identity.agents.config.load.interval). These two properties, which both control the hot-swap mechanism, are themselves hot-swap enabled. This means that if the hot-swap mechanism is enabled by one of these properties and you change the value of the respective property, the new value will take effect.

Locking J2EE Agent Properties


Caution – Caution –

Changing configuration properties can have unexpected results. Furthermore, hot-swappable properties take effect immediately. Therefore, configuration mistakes are instantly implemented.


You can lock the configuration to help prevent such accidental changes. Then you can unlock and lock the configuration as necessary.

ProcedureTo Lock the Agent Configuration Properties

  1. Using your text editor of choice, open the OpenSSOAgentBootstrap.properties file.

    The bootstrap file is available at the following location:

    PolicyAgent-base/AgentInstance-Dir/config/OpenSSOAgentBootstrap.properties
    

    For information about this location, see Table P–6

  2. In the bootstrap file, locate the following setting:

    com.sun.identity.agents.config.lock.enable = false

    This property is set to false, which is unlocked, by default.

  3. Change the false setting to true to lock the properties.

  4. Save and close the bootstrap file.

  5. Restart the agent instance container for the change to take effect.

J2EE Agent Properties That Are List Constructs

Certain J2EE properties are specified as lists. Knowledge of the format of these list constructs is often not required in order to set them. For example when you configure the properties using OpenSSO Enterprise Console, you do not interact with the “<key>[<index>] = <value>” formatting involved with list constructs. However, if you use OpenSSO Enterprise Console to set a list, though the formatting information provided in this section is not applicable, the general information about lists is useful.

See the following table to determine when the list construct format is required to set this property.

Table 4–1 Use of the List Construct Format: Required or Not

Method for Setting Properties

Location of Agent Configuration

Knowledge of List Construct Format Required

Using the OpenSSO Enterprise Console 

Centralized agent configuration 

NO 

Using the ssoadm command-line utility

Centralized agent configuration 

YES 

Using the OpenSSOAgentConfiguration.properties file

Local agent configuration 

YES 

A list construct has the following format (Does not apply when the OpenSSO Enterprise Console is used):

<key>[<index>] = <value>
key

The configuration key (name of the configuration property)

index

A positive number starting from 0 that increments by 1 for every value specified in this list.

value

One of the values specified in this list


Note –

Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties.

More than one property can be specified for this key by changing the value of <index>. This value must start from the number 0 and increment by 1 for each entry added to this list.

If certain indices are missing, those indices are ignored and the rest of the specified values are loaded at adjusted list positions.

Duplicate index values result in only one value being loaded in the indexed or adjusted indexed position.



Example 4–2 Example of J2EE Agent Properties That Are List Constructs

com.sun.identity.agents.config.notenforced.uri[0]=/agentsample/public/*
com.sun.identity.agents.config.notenforced.uri[1]=/agentsample/images/*
com.sun.identity.agents.config.notenforced.uri[2]=/agentsample/index.html

J2EE Agent Properties That Are Map Constructs

Knowledge of the format of these map constructs is often not required in order to set them. For example when you configure the properties using OpenSSO Enterprise Console, you do not interact with the “<key>[<name>]=<value>” formatting involved with map constructs. However, if you use OpenSSO Enterprise Console to set a map, though the formatting information provided in this section is not applicable, the general information about maps is useful.

See the following table to determine when the map construct format is required to set this property.

Table 4–2 Use of the Map Construct Format: Required or Not

Method for Setting Properties

Location of Agent Configuration

Use of Map Construct Format Required

Using the OpenSSO Enterprise Console 

Centralized agent configuration 

NO 

Using the ssoadm command-line utility

Centralized agent configuration 

YES 

Using the OpenSSOAgentConfiguration.properties file

Local agent configuration 

YES 

Certain J2EE agent properties are specified as maps. A map construct has the following format (Does not apply when OpenSSO Enterprise Console is used):

<key>[<name>]=<value>
key

The configuration key (name of the configuration property)

name

A string that forms the lookup key as available in the map

value

The value associated with the name in the map


Note –

Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties.

For a given <name>, there may only be one entry in the configuration for a given configuration key (<key>). If multiple entries with the same <name> for a given configuration key are present, only one of the values will be loaded in the system and the other values will be discarded.



Example 4–3 Example of J2EE Agent Properties That Are Map Constructs

com.sun.identity.agents.config.filter.mode[app1]=ALL
com.sun.identity.agents.config.filter.mode[app2]=SSO_ONLY

J2EE Property Configuration: Application Specific or Global

Certain J2EE agent properties can be configured for specific applications. Therefore, the agent can use different values of the same property for different applications as defined in the configuration file. Properties that are not configured for specific applications apply to all the applications on that deployment container. Such properties are called global properties.

Knowledge of the format of these application-specific constructs is often not required in order to set them. For example when you configure the properties using OpenSSO Enterprise Console, you do not interact with the “<key>[<appname>]=<value>” formatting involved with application-specific constructs. However, if you use OpenSSO Enterprise Console to set an application-specific property, though the formatting information provided in this section is not applicable, the general information about properties that can be both application-specfic and global is useful.

See the following table to determine when the application-specific construct format is required to set these types of properties.

Table 4–3 Use of the Map Construct Format: Required or Not

Method for Setting Properties

Location of Agent Configuration

Use of Application-Specific Construct Format Required

Using the OpenSSO Enterprise Console 

Centralized agent configuration 

NO 

Using the ssoadm command-line utility

Centralized agent configuration 

YES 

Using the OpenSSOAgentConfiguration.properties file

Local agent configuration 

YES 

An application-specific property has the following format (Does not apply when the OpenSSO Enterprise Console is used):

<key>[<appname>]=<value>
key

The configuration key (name of the configuration property)

appname

The application name to which this configuration belongs. The application name is the context path of the application without the leading forward slash character. In a scenario where the application has been deployed at the root-context of the server, the application name should be specified as DefaultWebApp.

value

The value used by the agent to protect the application identified by the given application name


Note –

When an application specific configuration is not present, the agent uses different mechanisms to identify a default value. Configurations are possible where the default value is used as the value specified for the same key without any application specific suffix [<appname>]. The following settings for a single property serve as an example:

com.sun.identity.agents.config.example[Portal] = value1
com.sun.identity.agents.config.example[DefaultWebApp] = value2
com.sun.identity.agents.config.example = value3

The preceding example illustrates that for applications other than the ones deployed on the root context and the context /Portal, the value of the property defaults to value3.


Application Specific configuration properties must follow the rules and syntax of the map construct of configuration entries.


Example 4–4 Example of Application Specific and Global Configuration

com.sun.identity.agents.config.example[Portal] = value1
com.sun.identity.agents.config.example[BankApp] = value2
com.sun.identity.agents.config.example[DefaultWebApp] = value3

J2EE Agent Filter Modes

The agent installation program and the agent property labeled Agent Filter Mode (com.sun.identity.agents.config.filter.mode) allow you to set the agent filter in one of the five available modes of operation. Depending upon your security requirements, choose the mode that best suits your site's deployment.

The value for the Agent Filter Mode property can be one of the following:

The sections that follow describe the different agent filter modes.

J2EE Agent Filter Mode-NONE

This mode of operation effectively disables the agent filter. When operating in this mode, the agent filter allows all requests to pass through. However, if the logging is enabled, the agent filter will still log all the requests that it intercepts.


Caution – Caution –

This mode is provided to facilitate development and testing efforts in a controlled development or test environment. Do not use this mode of operation in a production environment at any time.


When the agent filter is operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls will return a negative result regardless of the user.

J2EE Agent Filter Mode - SSO_ONLY

This is the least restrictive mode of operation for the agent filter. In this mode, the agent simply ensures that all users who try to access protected web resources are authenticated using OpenSSO Enterprise Authentication Service.

When operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls evaluated for the application will result in negative evaluation.

J2EE Agent Filter Mode - J2EE_POLICY

In this mode, the agent filter and agent realm work together with variousOpenSSO Enterprise services to ensure the correct evaluation of J2EE policies.

You can set these policies either in the application's deployment descriptors or, in cases where the application uses the J2EE programmatic security APIs, in the application code. URL policies that are defined in OpenSSO Enterprise do not take effect in this mode. If the application uses declarative security in the Web tier, you must configure the agent to enable that feature. See Enabling Web-Tier Declarative Security in J2EE Agents for more information on how to enable this feature. While running in the J2EE_POLICY mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.

J2EE Agent Filter Mode - URL_POLICY

In the URL_POLICY mode, the agent filter enforces the URL policies that are defined in OpenSSO Enterprise.

When the agent filter is in the URL_POLICY mode, the agent does not enforce any applicable J2EE declarative security policies. Such policies along with any calls to J2EE programmatic security API return negative results.

J2EE Agent Filter Mode - ALL

This is the most restrictive mode of the agent filter. In this mode, the filter enforces both J2EE policies and URL policies as defined in OpenSSO Enterprise. This mode of operation requires that the agent realm be configured in the deployment container. When running in the ALL mode, the agent ensures that the security principal is set in the system for every authorized access.

The ALL mode is highly recommended for deployed production systems.

Enabling Web-Tier Declarative Security in J2EE Agents

Certain applications might require the use of web-tier declarative security that enforces role-based access control over web resources such as Servlets, JSPs, HTML files and any other resource that can be represented as a URI. This type of security is enforced by adding security-constraint elements to the deployed application’s web.xml deployment descriptor.

Typically security-constraint elements are tied with auth-constraint elements that identify the role membership that will be enforced when a request for a protected resource is made by the client browser. The following example illustrates this idea:


<security-constraint>
   <web-resource-collection>
     <web-resource-name>Report Servlet</web-resource-name>
     <url-pattern>/ReportGenServlet</url-pattern>
   </web-resource-collection>
   <auth-constraint>
     <role-name>MANAGER</role-name>
   </auth-constraint>
</security-constraint>

   

This fragment of deployment descriptor can be used to ensure that access to the report generation servlet is allowed only to those users who are members of the role called Manager.

In order for such a construct to work, you must make the necessary modifications to the applicable J2EE agent properties to ensure it can identify and handle such requests.

ProcedureTo Enable J2EE Agents to Handle Security Constraint Settings

  1. Ensure that a login-config element is specified for the web application that is being protected and that the login-config element has the auth-method set to FORM.

    The supporting form-login-config element is also required.

  2. Add the form-login-page element of form-login-config as one of the values for the following agent property:

    com.sun.identity.agents.config.login.form

    As an example, consider the following login-config element of a protected application:


    <login-config>
       <auth-method>FORM</auth-method>
       <form-login-config>
          <form-login-page>/jsp/login.jsp</form-login-page>
          <form-error-page>/block.html</form-error-page>
       </form-login-config>
    </login-config>
    
                

    Notice how the form-login-page is specified for the supporting form-login-config element. This value must be set for the property labeled Login Form URI (Tab: Application, Name: com.sun.identity.agents.config.login.form). The following is a feasible value for this property:

    /Portal/jsp/login.jsp

    Notice that the value of the form-login-page as specified in the deployment descriptor is not the same as what is specified for the Login Form URI property. The difference being that when you enter this value in the configuration file, you must prefix it with the context path for the application on which this form-login-page is going to be used. In this particular example, the context path of the application is “/Portal.”

    Similarly, if you have more than one application deployed that require web-tier declarative security, you must add their respective form-login-pages to the property labeled Login Error URI (com.sun.identity.agents.config.login.error.uri). For example, The following are feasible values for the Login Error URI property:

    /BankApp/SignOn

    /ERP/LoginServlet

    Ensure that each such element added to this list has a unique index entry. Having duplicate index entries can result in the loss of data and consequently result in the malfunction of the application.

    Once you have configured the web application’s deployment descriptor to use the form-login mechanism for web-tier declarative security and have added the full URI of the form-login-page for each such application to the applicable agent property, the web-tier declarative security is enabled for these applications.


    Note –
    • When a protected application is configured for web-tier declarative security handling by the agent, it must be redeployed with a form-login configuration as described in this section. This configuration requires that two application resources be specified in the application’s web.xml deployment descriptor: one for the form-login-page and the other for the form-error-page. Regardless of whether the resource corresponding to the form-login-page exists in the application or not (this depends on how the agent is configured to handle the form-login requests), the resource corresponding to the form-error-page must be present in the application. This resource is directly invoked by the deployment container to indicate authentication failures and, optionally, authorization failures. If the application does not contain a valid form-error-page matching the URI specified in this deployment descriptor, it could result in HTTP 404 errors when the container chooses to display this error page.

    • For applications that do not contain a form-login-page, you can specify any URI as long as that URI does not conflict with any application resource and the matching value has been added to the configuration property com.sun.identity.agents.config.login.form.

    • By default, the agent is configured to intercept all form-login requests and handle them without invoking the actual form-login-page resource as specified in the web.xml of the protected application. Thus, when using a default installation of the agent, the application is not required to have a resource corresponding to the form-login-page element specified in web.xml. This allows for the configuration of web-tier declarative security for applications that were not designed to use the form-login mechanism and instead relied on other login schemes available in J2EE specification. This behavior of the agent can be changed so that it allows the form-login requests to be handled by actual resources that exist within the application by changing the agent configuration properties as applicable. For details on how this can be done, please refer to the section Customizing Agent Response for Form Login.

    • If the agent filter is operating in the URL_POLICY mode, any necessary URL policies to allow access to the form-error-page resource must be created for all users.

    To further customize the behavior of the application when using web-tier declarative security, see Web-Tier Security Details.


Web-Tier Security Details

When the deployment container gets a request for a resource that is protected by the web-tier declarative security-constraint, it must evaluate the credentials of the user against the agent realm to ensure that only authorized requests go through. In order to process such a request, the deployment container requires the user to sign on using the specified form login page as mentioned in the form-login-config element of the web.xml descriptor. Based on the specification of the FORM authentication mechanism, it is required that the user submits a valid user name as j_username and a valid password as j_password to the special URI j_security_check using the HTTP POST method of form submission.

The agent, once configured to support web-tier declarative security for the given application can isolate the request for accessing form-login-page and instead can stream out some data to the client browser. This data contains the user’s login name and temporary encrypted password, which in turn uses Javascript to do automatic form submission as required. This gives the user a seamless single sign-on experience since the user does not have to re-login in order to access the protected resources for a deployed application that uses web-tier declarative security.

By default, the content that the agent sends to the client browser on intercepting a request for the form login page is read from the file called FormLoginContent.txt located in the locale directory of the agent installation. This file contains the following HTML code:


<html>
   <head>
      <title>Security Check</title>
   </head>
   <body onLoad="document.security_check_form.submit()">
      <form name="security_check_form" action="j_security_check" method="POST">
         <input type="hidden" value="am.filter.j_username" name="j_username">
         <input type="hidden" value="am.filter.j_password" name="j_password">
      </form>
   </body>
</html>

      

Before the agent streams out the contents of this file, it replaces all occurrences of the string am.filter.j_username by the appropriate user name. Similarly, all occurrences of the string am.filter.j_password are replaced by a temporary encrypted string that acts as a one-time password for the user.

Customizing Agent Response for Form Login

J2EE agent properties allow you to completely control the content that is sent out to the user when the deployment container requires a form login from the user.


Note –

The ability to customize the agent response form login is not a feature whose purpose is to change the form login page nor is the purpose of this feature to bypass the default OpenSSO Enterprise login page.


Using the J2EE agent properties, you can customize the agent response in the following ways:

ProcedureTo Customize the Agent Response to Form Login

  1. Modify the content of the FormLoginContent.txt file to suit your UI requirements as necessary.

    Ensure that regardless of the modifications you make, the final file submits the j_username and j_password to the action j_security_check via HTTP POST method.

  2. (Conditional) You can specify the name of a different file by using the property labeled Login Content File Name (Tab: Application, Name: com.sun.identity.agents.config.login.content.file).

    If you specify the file name, you must ensure that it exists within the locale directory of the agent installation.

    If you wish that this file be used from another directory, you can simply specify the full path to this new file.

    Ensure that regardless of the modifications you make, the final file submits the j_username and j_password to the action j_security_check via HTTP POST method.

  3. (Conditional) If you have more than one application and would like to have an application-specific response to the form login requests, instruct the agent to allow the form login request to proceed to the actual form login page.

    This can be done by enabling the property labeled Use Internal Login (Tab: Application, Name: com.sun.identity.agents.config.login.use.internal).

    In this situation, you must ensure that the resource that receives this request extracts the am.filter.j_username and am.filter.j_password from the HttpServletRequest as attributes and uses that to ensure that eventually a submit of these values as j_username and j_password is done to the action j_security_check via HTTP POST method.

    The following JSP fragment demonstrates how this can be done:


    <form action="j_security_check" method="POST">
    <%
       String user = (String) request.getAttribute("am.filter.j_username");
       String password = (String) request.getAttribute("am.filter.j_password");
    %>
       <ul>
          <li>Your username for login is: <b><%=user%></b></li>
          <li>Your password for login is: <b><%=password%></b></li>
       </ul>
       <input type=hidden name="j_username" value="<%=user%>">
       <input type=hidden name="j_password" value="<%=password%>">
       <input type="submit" name="submit" value="CONTINUE">
    </form>
    
                   

    This mechanism would therefore allow you to have an application-specific form-login handling mechanism.

Enabling Failover in J2EE Agents

The agent allows basic failover capabilities. This helps you ensure that if the primary OpenSSO Enterprise instance for which the agent has been configured becomes unavailable, the agent will switch to the next OpenSSO Enterprise instance as specified by setting the appropriate agent property. This configuration can be achieved by implementing the following steps.

ProcedureTo Enable Failover in J2EE Agents

  1. Provide a list of OpenSSO Enterprise authentication services URLs that may be used by the agent to authenticate users who do not have sufficient credentials to access the protected resources.

    To create the list configure the property labeled OpenSSO Login URL (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.login.url).

    You may specify more than one login URL to this property as follows:

    primary-OSSO-server

    Represents the URL of the primary OpenSSO Enterprise instance to which users are redirected for authentication.

    failover-OSSO-server1

    Represents the URL of the OpenSSO Enterprise instance to which users are redirected for authentication if the primary OpenSSO Enterprise instance fails.

    failover-OSSO-server2

    Represents the URL of the OpenSSO Enterprise instance to which users are redirected for authentication if the primary OpenSSO Enterprise instance fails and the first failover OpenSSO Enterprise instance fails.

    If a URL list is provided to OpenSSO Login URL property, the agent first tries to establish a connection to the first server (primary-OSSO-server) specified in the URL list. If the agent is successful in establishing this connection, it redirects the user to the OpenSSO Enterprise instance for authentication.

  2. (Optional) Turn prioritization on for the failover lists by enabling the property labeled Login URL Prioritized (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.login.url.prioritized).


    Note –

    Enabling this property turns prioritization on for the login URL list and the CDSSO URL list. The two cases shown in this step specifically mention the login URL list. However, this explanation of prioritization is exactly the same for the CDSSO URL list. The final step in this procedure describes how to create the CDSSO URL list in case such a scenario applies to your site's deployment.


    The following cases describe the behavior of the agent in different situations: when you enable prioritization and when you do not enable prioritization for the login URL list.

    Case 1: The Login URL Prioritized property is enabled.

    Enabling this property means that priority is established for the login URL list described in Step 1. The list was created by configuring the property labeled Login URL.

    Therefore, the first URL on the list has a higher priority than the second URL on the list, which has a higher priority than the third URL on the list, and so on. If the server (primary-OSSO-server) specified in this example as the first URL on the list is running, the agent sends all requests to this server only. However, if primary-OSSO-server fails, from that point on, subsequent requests are sent to the server (failover-OSSO-server1), which is second on the list. Furthermore, if at some point primary-OSSO-server comes back, then the subsequent requests from that point on are sent to primary-OSSO-server, since it takes priority over failover-OSSO-server1. This mechanism always fails back to the highest priority OpenSSO Enterprise instance among the OpenSSO Enterprise instances that are running at the point in time the agent must redirect requests to an OpenSSO Enterprise instance.

    Case 2: The Login URL Prioritized property is not enabled.

    In this case, no server takes priority over another. Failover occurs in a round-robin fashion. If all the servers are running, the agent sends requests to the server (primary-OSSO-server), which is first on the list. If primary-OSSO-server goes down then all subsequent requests are sent to the server (failover-OSSO-server1), which is second on the list. The agent keeps sending the requests to failover-OSSO-server1 unless that server goes down. If failover-OSSO-server1 does go down then the agent routes all the subsequent requests to the server (failover-OSSO-server2), which is third on the list, until it goes down. If it goes down, the agent tries to connect to primary-OSSO-server once again. Assuming that by then the primary-OSSO-server is running, all the subsequent requests from then on are sent to primary-OSSO-server. This is a simple round-robin mechanism without any priority involved.

  3. Provide a list of OpenSSO Enterprise Naming Service URLs that may be used by the agent to get access to the various other service URLs that may be needed to serve the logged on user.

    This can be done by using the following property:

    com.iplanet.am.naming.url (accessible in the OpenSSOAgentBootstrap.properties file)

    More than one naming service URL may be specified as a space delimited list of URLs. The following example illustrates this idea:

    com.iplanet.am.naming.url = primary-OSSO-server failover-OSSO-server1

  4. (Conditional) If the deployment consists of an agent instance that is on a different domain than multiple OpenSSO Enterprise instances for which you want to enable failover, provide a URL list of the remote OpenSSO Enterprise instances.

    Configure the property labeled CDSSO Servlet URL (Tab: SSO, Name: com.sun.identity.agents.config.cdsso.cdcservlet.url) to create the list, specifying multiple CDSSO URLs as such:

    primary-remoteOSSO-server

    failover-remoteOSSO-server1

    failover-remoteOSSO-server2

Login Attempt Limit in J2EE Agents

When a user tries to access a protected resource without having authenticated with OpenSSO Enterprise Authentication Services, the request is treated as a request with insufficient credentials. The default action taken by the agent when it encounters such a request is to redirect the user to the next available login URL as configured with the property labeled Login Attempts Limit (Tab: Global, Name: com.sun.identity.agents.config.login.attempt.limit).

Despite the repeated redirects performed by the agent, the user could still be unable to furnish the necessary credentials. In such a case, the agent can be directed to block such a request.

If a non-zero positive value is specified for this property, the agent will only allow that many attempts before it blocks the access request without the necessary credentials. When set to a value of zero, this feature is disabled.

To guard against potential denial-of-service attacks on your system, enable this feature.

Redirect Attempt Limit in J2EE Agents

The processing of requests by the agent can result in redirects for the client browser. Such redirects can happen when the user has not authenticated with OpenSSO Enterprise Authentication Service, lacks the sufficient credentials necessary to access a protected resource, and a variety of other reasons.

While the agent ensures that only the authenticated and authorized users get access to the protected resources, there is a remote possibility that due to misconfiguration of the system, the client browser may be put into an infinite redirection loop.

The property labeled Redirect Attempt Limit (Tab: Global, Name: com.sun.identity.agents.config.redirect.attempt.limit) allows you to guard against such potential situations by ensuring that after a given number of consecutive requests from a particular user that result in the same exact redirect, the agent blocks the user request. This blocking of the request is only temporary and is removed the moment the user makes a request that does not result in the same redirect or results in access being granted to the protected resource.

If a non-zero positive integer is specified as the value of this property, the agent will break the redirection loop after the specified number of requests result in the same redirects. When its value is set to zero, this feature is disabled.

To protect the system from such situations, enable this feature. Furthermore, enabling this feature can help in breaking potential denial of service attacks.

Not-Enforced URI List in J2EE Agents

Agents in the Policy Agent 3.0 software set allow you to specify a list of URIs that are treated as not-enforced. Access to these resources is always granted by the agent. The property labeled Not Enforced URIs (Tab: Application, Name: com.sun.identity.agents.config.notenforced.uri) controls the list.

If your deployed application has pages that use a bulk of graphics that do not need the agent protection, such content should probably be added to the agent’s not-enforced list to ensure the optimal utilization of the system resources. Following is an OpenSSO Enterprise Console example of the entries that you can specify in the not-enforced list:

/images/*

/public/*.html

/registration/*

This enables the agent to focus on enforcing access control only over requests that do not match these given URI patterns. The use of a wildcard (*) is allowed to indicate the presence of one or more characters in the URI pattern being specified. For more information about the use of wildcards with OpenSSO Enterprise and Policy Agent, see Appendix C, Wildcard Matching in Policy Agent 3.0 J2EE Agents.

Inverting the Not-Enforced URI List

In situations where only a small portion of the deployed application needs protection, you can configure the agent to do just that by inverting the not-enforced list. This results in the agent enforcing access control over the entries that are specified in the not-enforced list and allowing access to all other resources on the system. This feature is controlled by the property labeled Invert Not Enforced URIs (Tab: Application, Name: com.sun.identity.agents.config.notenforced.uri.invert).

When you enable this property, it changes the entries specified in the not-enforced list to enforced and the rest of the application resources are treated as not-enforced.


Caution – Caution –

When the not-enforced list is inverted, the number of resources for which the agent will not enforce access control is potentially very large. The use of this feature should therefore be used with extreme caution and only after extensive evaluation of the security requirements of the deployed applications.



Note –

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:

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:

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

Configuring FQDN Handling in J2EE Agents

To ensure appropriate user experience, the use of valid URLs by users to access resources protected by the agent must be enforced. This functionality is controlled by three separate properties:

FQDN Check (Tab: Global, Name: com.sun.identity.agents.config.fqdn.check.enable)

Enables FQDN Check

FQDN Default (Tab: Global, Name: com.sun.identity.agents.config.fqdn.default)

Stores the default FQDN value

FQDN Virtual Host Map (Tab: Global, Name: com.sun.identity.agents.config.fqdn.mapping)

Sets FQDN mapping

The property labeled FQDN Default provides the necessary information needed by the agent to identify if the user is using a valid URL to access the protected resource. If the agent determines that the incoming request does not have a valid hostname in the URL, it redirects the user to the corresponding URL with a valid hostname. The difference between the redirect URL and the URL originally used by the user is only the hostname, which is now changed by the agent to a fully qualified domain name (FQDN) as per the value specified in this property.

The property labeled FQDN Virtual Host Map provides another way by which the agent can resolve malformed access URLs used by users and take corrective action. The agent gives precedence to entries defined in this property over the value defined in the FQDN Default property. If none of the entries for this property matches the hostname specified in the user request, the agent uses the value specified for FQDN Default property to take the necessary corrective action.

The FQDN Virtual Host Map property can be used for creating a mapping for more than one hostname. This can be done when the deployment container protected by this agent can be accessed using more than one hostname. As an example, consider a protected deployment container that can be accessed using the following host names:

In this case, assuming that www.externalhostname.com is the value assigned to the FQDN Default property, then the FQDN Virtual Host Map property can be configured using OpenSSO Enterprise Console as follows to allow access to the application for users who will use the hostname internalhostname.interndomain.com or the raw IP address, 192.101.98.45:

Map Key

internalhostname.interndomain.com

Corresponding Map Value

internalhostname.interndomain.com

Map Key

192.101.98.45

Corresponding Map Value

192.101.98.45

When you are done setting the FQDN Virtual Host Map property as described in this example, it appears in OpenSSO Enterprise Console with the following format:


[internalhostname.interndomain.com] = internalhostname.interndomain.com

[192.101.98.45] = 192.101.98.45

Using Cookie Reset Functionality in J2EE Agents

The agent allows you to reset certain cookies that might be present in the user’s browser session if the user’s OpenSSO Enterprise session has expired. This feature is controlled by the following configuration properties:

The preceding four properties can be used to specify the exact details of the cookie that should be reset by the agent when a protected resource is accessed without a valid session.

The property labeled Cookies Reset Name List specifies a list of cookie names that will be reset by the agent when necessary. Each entry in this list can correspond to a maximum of one entry in the properties labeled Cookies Reset Domain Map and Cookies Reset Path Map, both of which are used to define the cookie attributes - the domain on which a particular cookie should be set and the path on which it will be set.

When using this feature, ensure that the correct values of the domain and path are specified for every cookie entry in the cookie list. If these values are inappropriate, the result might be that the cookie is not reset in the client browser.

When a cookie entry does not have an associated domain specified in the domain map, it is handled as a server cookie. Similarly, when a cookie entry does not have a corresponding path entry specified, the anticipated cookie path is “/.”

Enabling Port Check Functionality in J2EE Agents

In situations when OpenSSO Enterprise and the deployment container are installed on the same system but on different ports, certain browsers may not send the HOST header correctly to the agent in situations where there are redirects involved between OpenSSO Enterprise Authentication Service and the agent. In such situations, the agent, relying on the availability of the port number from the deployment container, might misread the port number that the user is trying to access.

When such a situation occurs, it can have a severe impact on the system since the agent now senses a resource access that in reality did not occur and consequently the subsequent redirects as well as any policy evaluations may fail thereby making the protected application inaccessible to the end user.

This situation can be controlled by enabling port check functionality on the agent. This is controlled by the property labeled Port Check Enable (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.enable).

When this property is enabled, the agent verifies the correctness of the port number read from the request against its configuration. The configuration that provides the reference for this checking is set by the property labeled Port Check Setting (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.setting).

This property allows the agent to store a map of various ports and their corresponding protocols. When the agent is installed, this map is populated by the preferred port and protocol of the agent server as specified during the installation. However, if the same agent is protecting more than one HTTP listeners, you must add that information to the map accordingly.

When the agent discovers an invalid port in the request, it takes corrective action by sending some HTML data to break the redirection chain so that the browser can reset its HOST header on the subsequent request. This content is read from the file that resides in the locale directory of agent installation. The name of the file is controlled by the property labeled Port Check File (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.file).

This property can also be used to specify the complete path to the file that may be used to achieve this functionality. This file contains special HTML that uses a META-EQUIV REFRESH tag in order to allow the browser to continue automatically when the redirect chain is broken. Along with this HTML, this file must contain the string am.filter.request.url, which is dynamically replaced by the actual request URL by the agent.

You can modify the contents of this file or specify a different file to be used, if necessary, so long as it contains the am.filter.request.url string that the agent can substitute in order to construct the true request URL with the correct port. The contents of this file should be such that it should either allow the user to automatically be sent to this corrected location or let the user click a link or a button to achieve the same result.

Web Services Security Support for J2EE Agents in Policy Agent 3.0

A web service is a software system identified by a URI, whose public interfaces and bindings are defined and described using XML. The definition for a given web service can be discovered by other software systems. These systems can then interact with the web service in a manner prescribed by its definition, using XML-based messages conveyed by Internet protocols.

A web service consists of two main components, a web service client (WSC) and a web service provider (WSP). A web service client is a software component that acts as a requester for a certain service using web service interface. A web service provider is a software component that provides the service.

J2EE agents in the Policy Agent 3.0 support Web Services Security for web service providers. A web service provider deployed on an application server protected by a J2EE agent instance can have additional security provided by the agent. Together, J2EE agent software and OpenSSO Enterprise server support various Web Services Security profiles including UsernameToken, X509Token, and SAML2 Token.

The task that follows describes how to configure Web Services Security support in J2EE Agents for Policy Agent 3.0.

ProcedureTo Configure Web Services Security Support in J2EE Agents for Policy Agent 3.0

Before You Begin

The instructions that follow start with the assumption that OpenSSO Enterprise server and a J2EE agent instance have been properly installed and configured.

  1. Create a web service provider configuration for the web service provider endpoint protected by the J2EE Agent instance as follows:

    1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

      The OpenSSO Enterprise login page is available at a URL similar in format to the following:

      http://OpenssoHost.example.com:58080/opensso
    2. Click the Access Control tab.

    3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

    4. Click the Agents tab.

    5. Click the Web Service Provider tab.

    6. Click the New button in the Agent section.

    7. Enter the full URL of the web service provider endpoint as the name of the Web Service Provider agent.

      For example, http://myhost.mydomain.com:8080/StockService/StockService.

    8. Enter a password.

    9. Click the Create button.

  2. Create an agent authenticator type agent profile as follows.

    This agent and its password will be used for the agent to authenticate to the OpenSSO Enterprise server.

    Fore more information about the agent authenticator, see About the Agent Authenticator in Policy Agent 3.0.

    1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

    2. Click the Access Control tab.

    3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

    4. Click the Agents tab.

    5. Click on Agent Authenticator tab.

    6. Click the New button.

    7. Enter an agent authenticator name and password.

    8. Click the Create button.

    9. On the Agent Authenticator page, click the link for the newly created agent authenticator.

      The agent authenticator page is displayed. In the section labeled "Agent Profiles allowed to Read," two lists exist: Available and Selected. The Available list has all the available agents in the system, and the Selected list has all the agents whose configurations can be read by this agent authenticator.

    10. From the available list, select the following items:

      • The J2EE agent profile name (this is the profile name of a previously installed J2EE agent instance)

      • The web service provider agents protected by the J2EE agent

      • The item labeled SecurityTokenService

    11. Click Add to move the selected items from the Available list to the Selected list

    12. Click Save

  3. Stop the agent container.

  4. Edit the OpenSSOAgentBootstrap.properties file of the previously installed J2EE agent, as follow:

    The bootstrap file is located at the following location:

    PolicyAgent-base/AgentInstance-Dir/config
    

    For information about this location, see Table P–6

    1. Using your text editor of choice, open the OpenSSOAgentBootstrap.properties file.

    2. At the end of the bootstrap file, add five lines as follows:

      1. Add the following line:

        com.sun.identity.wss.trustclient.enablemetro=false
      2. Add the four following lines related to keystore information.

        The various place holders for these four lines must be replaced with the actual keystore information.

        com.sun.identity.saml.xmlsig.keystore=KeystorePathName
        com.sun.identity.saml.xmlsig.storepass=FileContainingEncryptedKeystorePassword
        com.sun.identity.saml.xmlsig.keypass=FileContainingEncryptedKeyPassword
        com.sun.identity.saml.xmlsig.certalias=KeyAliasName
        
    3. Change the value for the property named com.sun.identity.agents.app.username to the agent authenticator name.

      Therefore, the setting would be as such:

      com.sun.identity.agents.app.username = AgentAuthenticatorName
      

      where AgentAuthenticatorName represents the name provided for the agent authenticator as demonstrated previously in this task.

    4. Change the value for the property named com.iplanet.am.service.secret to the agent authenticator password.

      Therefore, the setting would be as such:

      com.iplanet.am.service.secret = EncryptedAgentAuthenticatorPassword
      

      where EncryptedAgentAuthenticatorPassword represents the encrypted version of the password provided for the agent authenticator as demonstrated previously in this task.


      Note –

      To encrypt the password, use the agentadmin --encrypt command as described in agentadmin --encrypt.


    5. Save and close the bootstrap file.

  5. Configure the J2EE agent to enable Web Services Security as follows:

    1. Using a browser, navigate through OpenSSO Enterprise Console to the agent properties of the J2EE agent that you want to configure.

      For the steps to navigate to the J2EE agent properties, see To Navigate in OpenSSO Enterprise 8.0 Console to the J2EE Agent Properties.

    2. Enable the property labeled Web Service Enable (Tab: Advanced, Name: com.sun.identity.agents.config.webservice.enable)

    3. Add the web service endpoint URIs as values for the property labeled Web Service End Points (Tab: Advanced, Name: com.sun.identity.agents.config.webservice.endpoint) as follows:

      1. Add a value, such as /StockService/StockService, in the New Value field and.

      2. Click Add.

    4. Add the web service endpoint related WSDL to the not enforced URI list (Tab: Advanced, Name: com.sun.identity.agents.config.notenforced.uri) as follows:

      com.sun.identity.agents.config.notenforced.uri[n]=your-wsp-endpointuri?wsdl*

      For example:

      com.sun.identity.agents.config.notenforced.uri[0]=/StockService/StockService?wsdl*

    5. Click Save on the Advanced page.

  6. Change the Security Token Service as follows:

    1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

    2. Click the Configuration tab.

    3. Click the Global tab.

    4. Click Security Token Service in the Global Properties list.

    5. Add a new value to the property labeled For the Trusted Issuers, in the Token Validation Attributes section as follows:

      1. For the Trusted Issuers property, enter the fully qualified domain name of the OpenSSO Enterprise server in the New Value field.

      2. Click Add.

      3. Click Save on the Security Token Service page.

  7. Set up a Web Services Security profile by following the substep alternative that fits your site's requirements.

    The J2EE agents in the Policy Agent 3.0 software set together with OpenSSO Enterprise server support various Web Services Security profiles including UsernameToken, X509Token, and SAML2 Token. The following alternative steps describe how to set up the four different profiles. Implement the substeps for the appropriate profile for your site's deployment.

    • Set up the UsernameToken-Plain profile as follow:

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Click the Access Control tab.

      3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

      4. Click the Agents tab.

      5. Click the Web Service Provider sub tab.

      6. Click the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      7. Select the checkbox next to UserNameToken-Plain to choose it as a Security Mechanism.

      8. In the Authentication Chain drop-down list, select ldapService.

      9. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      10. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      11. Click Save on that page.

      12. Click “Back to Main Page.”

      13. Click the Web Service Client subtab.

      14. Click the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      15. Select UserNameToken-Plain as the Security Mechanism.

      16. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      17. Click Save on that page.

    • Set up the X509Token profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Create an authentication module, such as certmod, assigning the following type: Certificate.

        See the Sun OpenSSO Enterprise 8.0 Administration Guide for more information about creating authentication modules and authentication chains.

      3. Create an authentication chain, such as certauth, that includes the module, such as certmod, that you just created in the previous substep.

      4. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      5. Select the checkbox next to X509Token to choose it as a Security Mechanism.

      6. In the Authentication Chain drop-down list, select the newly created authentication chain, such as certauth.

      7. In the "Web Service End Point" field, enter the name of web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      8. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      9. Click Save on that page.

      10. Click “Back to Main Page.”

      11. Click the Web Service Client subtab.

      12. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      13. Select X509Token as the Security Mechanism.

      14. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      15. Click Save on that page.

    • Set up the SAML2-HolderOfKey profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      3. Select the checkbox next to SAML2-HolderOfKey to choose it as a Security Mechanism.

      4. In the Authentication Chain drop-down list, select ldapService.

      5. If not already entered, enter urn:sun.wss.ssotoken in the field for Token Conversion Type.

      6. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      7. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      8. Click Save on that page.

      9. Click “Back to Main Page.”

      10. Click the Web Service Client subtab.

      11. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      12. Select SAML2-HolderOfKey as the Security Mechanism.

      13. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      14. Click Save on that page.

    • Set up the SAML2-SenderVouches profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      3. Select the checkbox next to SAML2-SenderVouches to choose it as a Security Mechanism.

      4. In the Authentication Chain drop-down list, select ldapService.

      5. If not already entered, enter urn:sun.wss.ssotoken in the field for Token Conversion Type.

      6. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      7. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      8. Click Save on that page.

      9. Click “Back to Main Page.”

      10. Click the Web Service Client subtab.

      11. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      12. Select SAML2-SenderVouches as the Security Mechanism.

      13. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      14. Click Save on that page.

  8. Enable Web Services Security in the web service provider as described in the substeps that follow.

    1. Using your text editor of choice, open the web.xml file of the web service provider.

    2. Add the agent filter element as the first filter in the web.xml file.

      For example, add the following:

            <filter>
                <filter-name>Agent</filter-name>
                <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
            </filter> 
    3. Add the agent filter mapping element as the first filter mapping in the web.xml file.

      For example, add the following:

            <filter-mapping>
                <filter-name>Agent</filter-name>
                <url-pattern>/*</url-pattern>
                <dispatcher>REQUEST</dispatcher>
                <dispatcher>INCLUDE</dispatcher>
                <dispatcher>FORWARD</dispatcher>
                <dispatcher>ERROR</dispatcher>
            </filter-mapping> 
    4. Save and close the web.xml file.

  9. Recreate the web service provider .war file.

  10. Redeploy the web service provider on the application server.

Resetting the J2EE Agent Profile Password in Policy Agent 3.0

Agents in the Policy Agent software set must authenticate with the OpenSSO Enterprise server in order for the two components to interact. To authenticate, the agent must provide its name (the agent profile name) and agent profile password. This password was established and encrypted as part of the J2EE agent installation process. For more information, see Creating a J2EE Agent Profile in Policy Agent 3.0 Using OpenSSO Enterprise Console. However, you can change this password if you choose.

The agent profile password can be reset with a combination of configuration steps involving both the OpenSSO Enterprise Console and the OpenSSOAgentBootstrap.properties file. The agent profile password should originally be created prior to agent installation. However, after you install a J2EE agent, you can update the agent profile password at anytime.

ProcedureTo Update a J2EE Agent Profile Password in Policy Agent 3.0

The instructions that follow describe how to change agent profile password.

  1. Using a browser, navigate through OpenSSO Enterprise Console to the J2EE agent properties of the agent that you want to configure.

    For the steps to navigate to the J2EE agent properties, see To Navigate in OpenSSO Enterprise 8.0 Console to the J2EE Agent Properties.

  2. Update the agent profile password in the J2EE agent properties section as described in the substeps that follow:

    1. In the Global tab ( which is the default tab), locate the property labeled Password.

    2. Update the Password property to a password of your choice.

    3. Update the property labeled “Password (confirm)” to the same value you chose for the Password property.

    4. Click Save at the top of that Global page.

  3. Update or create an agent profile password in a password file as described in the substeps that follow.

    The password file should originally have been created as a J2EE agent pre-installation task.

    1. (Conditional) If an ASCII text agent password file does not already exist, create one .

      For example, create a file such as the following: /tmp/pwf1

    2. Using your text editor of choice, enter in clear text on the first line, (or replace the original password, if one already exists with) the password you just updated in OpenSSO Enterprise Console.

    3. Secure the password file appropriately, depending on the requirements for your deployment.

  4. In the command line, issue the agentadmin --encrypt command to encrypt the new password.

    For example:

    PolicyAgent-base/bin/agentadmin --encrypt Agent_001 /tmp/pwf1 

    The agentadmin program returns the new encrypted password with a message such as the following:

    The encrypted value is: AQICFtkDruE1iBJrZvPW2Yfpgitm/3NjmpIQ

    For more information on this command, see agentadmin --encrypt.

  5. Copy the encrypted value that is returned.

  6. Using your text editor of choice, access the J2EE agent OpenSSOAgentBootstrap.properties configuration file at the following location:

    PolicyAgent-base/AgentInstance-Dir/config
    
  7. In the bootstrap configuration file, edit the property for the agent password as follows:

    com.iplanet.am.service.secret = encryptedPassword
    

    where encryptedPassword represents the new encrypted password you created when you issued the agentadmin --encrypt command.

    This property is set in a manner similar to the following:

    com.iplanet.am.service.secret=AQICFtkDruE1iBJrZvPW2Yfpgitm/3NjmpIQ
  8. Restart the J2EE agent container.

    The container must be restarted for the changes to the bootstrap file to take effect.

Key Features and Tasks Performed With the J2EE agentadmin Program

The agentadmin program is a utility used to perform a variety of tasks from required tasks, such as installation to optional tasks, such as displaying version information. This section summarizes the tasks that can be performed with the agentadmin program. Many of the tasks performed with this program are related to installation or uninstallation. For detailed information about the options available with this program, see Role of the agentadmin Program in Policy Agent 3.0.

In this section, the options are listed for your quick review to help you get a sense of how the agentadmin program fits in with the other methods of managing J2EE agents, which are all discussed in this chapter.

The location of the agentadmin program is as follows:

PolicyAgent-base/bin

For information about the location of PolicyAgent-base, see Table P–5.

The following table lists options that can be used with the agentadmin command and gives a brief description of the specific task performed with each option.

Table 4–4 The agentadmin Program: Supported Options

Option 

Task Performed 

--install

Installs a new agent instance 

--custom-install

Installs a new agent instance 

--uninstall

Uninstalls an existing Agent instance 

--listAgents

Displays details of all the configured agents 

--agentInfo

Displays details of the agent corresponding to the specified agent IDs 

--version

Displays the version information 

--encrypt

Encrypts a given string 

--getEncryptKey

Generates an Agent Encryption key 

--uninstallAll

Uninstalls all agent instances 

--migrate

Migrates agent to a newer version 

--usage

Displays the usage message 

--help

Displays a brief help message 

Key Features and Tasks Performed With the J2EE Agent API

The agent runtime provides access to all the OpenSSO Enterprise application program interfaces (API) that can be used to further enhance the security of your application. Besides the OpenSSO Enterprise API, the agent also provides a set of API that allow the application to find the SSO token string associated with the logged-in user. These API can be used from within the web container or the EJB container of the deployment container. These are agent utility API. However, an equally viable option is to use client SDK public API directly to fetch the SSO token.


Note –

Certain containers, such as Apache Tomcat Servlet/JSP Container do not have an EJB container. Hence, the EJB related agent API would not be applicable for such containers.


The subsections that follow illustrate the available agent API that can be used from within an application. The J2EE agent API have changed in Policy Agent 3.0 as explained in this section. This section includes an example of the new API in use, see Usage of New J2EE Agent API in Policy Agent 3.0.

Class AmFilterManager

com.sun.identity.agents.filter.AmFilterManager

Available API for Class AmFilterManager

Interface IAmSSOCache

com.sun.identity.agents.filter.IAmSSOCache

Available API for Interface IAmSSOCache

public String getSSOTokenForUser(Object ejbContextOrServletRequest)

This method can be used to retrieve the SSO token for the logged-in user. If called from the web tier, this method passes an instance of javax.servlet.http.HttpServletRequest as an argument. If called from the EJB tier, this method passes an instance of javax.ejb.EJBContext as an argument. This method eradicates the need to use two separate methods in AmSSOCache to retrieve the SSO token.

Class AmSSOCache

com.sun.identity.agents.filter.AmSSOCache

Note –

Deprecated: This class and its methods have been deprecated. The best practice is not to use the methods in this class, but to use the unified API in com.sun.identity.agents.filter.IAmSSOCache.


Available API for Class AmSSOCache


Note –

The API getSSOTokenForUser(javax.ejb.EJBContext) can be used only when the agent operation mode is either J2EE_POLICY or ALL.


Usage of New J2EE Agent API in Policy Agent 3.0

The following example demonstrates the new J2EE agent API in use.


Example 4–5 Usage of New J2EE Agent API

String ssotoken = 
AmFilterManager.getAmSSOCache().getSSOTokenForUser(EJBContext);


Caution – Caution –

This public API can only retrieve the SSOToken object in EJB context if the value of the following property labeled User Principal Flag (com.sun.identity.agents.config.user.principal) is enabled