test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for IBM WebSphere Application Server 6.1/7.0 and WebSphere Portal Server 6.1

Required Post-Installation Tasks for the WebSphere Application Server/Portal Server Agent

Creating an Agent User

The agent user is required for integration with the WebSphere Application Server 6.1/7.0 Console.

ProcedureTo Create an Agent User

  1. Login into the OpenSSO Enterprise Administration Console.

  2. Click Access Control, realm-name, Subjects, and then User.

  3. Click New and enter values for the following fields:

    • ID: Name of the primary agent user. For example: agentuser

    • First Name: Not required. You can leave this field blank.

    • Last Name and Full Name: For simplicity, use the same name for each of these values that you specified for ID.

    • Password (and confirm): Password for the agent user.

      Note: Be sure to save this password, because you will need to encrypt it later.

    • User Status: Active

  4. Click OK.

    The console creates the agent user and displays the User page again with a link to the new agent user, agentuser.

    To do additional configuration for the agent profile, click this link to display the Edit User page. For information about the configuration fields, see the Console online Help.

Creating a New Agent Group for the Agent User

The agent profile group is created specifically for the agent user and allows the agent user to access user attributes in the user repository.

Note –

In the Access Manager 7.1 and Access Manager 7 2005Q4 releases, the agent user was assigned a specific role. OpenSSO Enterprise uses groups rather than roles for the same functionality.

ProcedureTo Create a New Agent Group for the Agent User

  1. Login to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm for which you would like to create the agent group.

  3. Click Subjects and then Group.

  4. Click New and then enter a name for the agent group. For example: agentusergroup

  5. Click OK.

  6. Under Group, click the agent user group (agentusergroup).

  7. On the Edit Group page, click User.

  8. Select the agent user (agentuser) under Available and click Add.

  9. Click Save.

Assigning Access Privileges to the Agent Group

ProcedureTo Assign Access Privileges to the Agent Group

  1. Login to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm where you created the agent group.

  3. Click Privileges.

  4. Click the agent profile group. For example: agentusergroup

  5. On the Privileges page, check:

    Read and write access to all realm and policy properties

  6. Click Save.

Creating the Primary Administrative User in OpenSSO Enterprise

If WebSphere global security is enabled, this user will be able to login to the WebSphere Administration Console.

ProcedureTo Create the Primary Administrative User in OpenSSO Enterprise

  1. Login to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm for which you would like to create the primary administrative user.

  3. Click Subjects and then User.

  4. Click New and enter values for the following fields:

    • ID: Name of the primary administrative user. For example: wasadmin

    • First Name: Not required. You can leave this field blank.

    • Last Name and Full Name: For simplicity, use the same name for each of these values that you specified for ID.

    • Password (and confirm): Password for the primary administrative user.

    • User Status: Active

  5. Click OK.

Creating the WebSphere Administrative Group in OpenSSO Enterprise

Any user in this group, in addition to the primary administrative user, can log in to the WebSphere Administration Console.

Note –

In the Access Manager 7.1 and Access Manager 7 2005Q4 releases, the user was assigned a specific role. OpenSSO Enterprise uses groups rather than roles for the same functionality.

ProcedureTo Create the WebSphere Administrative Group in OpenSSO Enterprise

  1. Login to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm for which you would like to create the WebSphere administrative group.

  3. Click Subjects and then Group.

  4. Click New and enter the name for the WebSphere administrative group. For example: wasadmingroup

    Important: Use all lowercase characters for the group name; otherwise, WebSphere might not recognize the name.

  5. Click OK.

  6. On the returned page, click the WebSphere administrative group (wasadmingroup).

  7. Click User.

  8. Select the primary administrative user (wasadmin) and any other users you want to be able to log in to the WebSphere Administration Console and click Add.

  9. Click Save.

Enabling Cookie Reset for the Agent Profile

ProcedureTo Enable Cookie Reset for the Agent Profile

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm.

  3. Click Agents, J2EE, and then the name of the agent profile.

  4. Click SSO.

  5. Under Cookie Reset:

    • Enable Cookie Reset.

    • In the Cookies Reset Name List, add LtpaToken and LtpaToken2.

      The corresponding configuration properties are:

      com.sun.identity.agents.config.cookie.reset.enable = true
com.sun.identity.agents.config.cookie.reset.name[0] = LtpaToken
com.sun.identity.agents.config.cookie.reset.name[1] = LtpaToken2

    These properties are hot-swappable, so you do not need to restart the OpenSSO Enterprise web container instance.

  6. Click Save.

Specifying the Agent User in the OpenSSOAgentBootstrap.properties File

The OpenSSOAgentBootstrap.properties file contains the properties required for the agent to start, initialize itself, and connect to the OpenSSO Enterprise server.

The OpenSSOAgentBootstrap.properties is located in the following directory on the server where the WebSphere Application Server/Portal Server agent is installed:

Agent-HomeDirectory/j2ee_agents/websphere_v61_agent/agent-instance/config

For example: /agents/j2ee_agents/websphere_v61_agent/Agent_001/config/

ProcedureTo Specify the Agent User the OpenSSOAgentBootstrap.properties File

  1. Logon to the server where the WebSphere Application Server/Portal Server agent is installed.

  2. Encrypt the password of the agent user (agentuser) that you created in the OpenSSO Enterprise Console under Creating an Agent User.

    1. Copy the unencrypted password to the agent profile password file (wsasagentpw).

    2. Change to the PolicyAgent-base/bin directory.

    3. Encrypt the agent user password using the agentadmin --encrypt command following this syntax:

      agentadmin --encrypt agent-instance password-file

      For example: # ./agentadmin --encrypt Agent_001 wsasagentpw

      The command returns the encrypted password. For example: ASEWEJIowNBJHTv1UGD324kmT==

  3. In the OpenSSOAgentBootstrap.properties file, set the following properties:

    • com.sun.identity.agents.app.username = agentuser

    • com.iplanet.am.service.secret = encrypted-agentuser-password

    • com.sun.identity.agents.config.profilename = agentprofile

    where:

    • agentuser is the agent user you created in the OpenSSO Enterprise Console.

    • encrypted-agentuser-password is the agent user encrypted password from Step 1.

    • agentprofile is the WebSphere Application Server/Portal Server agent profile.

  4. Restart the WebSphere Application Server/Portal Server agent web container.

Performing Global Configuration Tasks for WebSphere Application Server 6.1/7.0

The tasks in this section enable the WebSphere Application Server/Portal Server agent to protect both web applications and the WebSphere Application Server 6.1/7.0 Administration Console.

You perform the following tasks only once for each WebSphere Application Server 6.1/7.0 node, regardless of the number of WebSphere Application Server 6.1/7.0 instances that exist within the node.

Setting the WebSphere Application Server 6.1/7.0 Custom Registry

ProcedureTo Set the WebSphere Application Server 6.1/7.0 Custom Registry

  1. If needed, start the WebSphere Application Server 6.1/7.0 instance.

    For example, for an instance named host1: ./startServer host1

  2. Log in to the WebSphere Application Server 6.1/7.0 Administration Console.

  3. Navigate to the Custom user registry page.

    1. Expand the Security node.

    2. Click “Secure administration, applications, and infrastructure”. A new page opens.

      For WebSphere Application Server 7.0, click “Global Security”.

    3. Under the Available realm definitions field, select Standalone custom registry.

    4. Click the Set as current button.

    5. Click the Configure button. A new page opens.

  4. Set the provider of the custom registry.

    1. In the Custom Registry class name field, replace the existing value with the following value:

      com.sun.identity.agents.websphere.AmAgentUserRegistry

    2. In the “Primary administrative user name” field, enter the administrative user name, which was previously created in OpenSSO Enterprise. For example: wasadmin

    3. For the Server user identity option, select “Automatically generated server identity”.

    4. Click OK. The page returns to “Secure administration, applications, and infrastructure”.

      For WebSphere Application Server 7.0, it's “Global Security”.

    5. Click the “Save directly to the master configuration” link.

Adding an OpenSSO Enterprise Trust Association Interceptor to WebSphere Application Server 6.1/7.0

This task allows the agent to establish single sign-on (SSO) with the protected WebSphere Application Server 6.1/7.0 instance.

ProcedureTo Add an OpenSSO Enterprise Trust Association Interceptor to WebSphere Application Server 6.1/7.0

  1. Log in to the WebSphere Application Server 6.1/7.0 Administration Console.

  2. Navigate to the Interceptors page:

    1. Expand the Security node.

    2. Click “Secure administration, applications, and infrastructure”. A new page opens.

      For WebSphere Application Server 7.0, click “Global Security”.

    3. Under the “Authentication” option, expand “Web security”.

      For WebSphere Application Server 7.0, expand “Web and SIP Security”.

    4. Click “Trust association”. The “Trust association” page opens.

    5. Click the Interceptors link. The Interceptors page opens.

  3. Click New. A new page opens.

  4. In the “Interceptor class name” field, enter:

    com.sun.identity.agents.websphere.AmTrustAssociationInterceptor

  5. Click OK. The browser returns to the Interceptor page.

  6. Click “Save directly to the master configuration”.

  7. Navigate again to the Interceptors page by clicking the “Trust association” link at the top of the page.

  8. Check the “Enable trust association” checkbox.

  9. Click OK. The page returns to “Secure administration, applications, and infrastructure”.

    For WebSphere Application Server 7.0, it's “Global Security”.

  10. Click “Save directly to the master configuration”.

Enabling Global Security for WebSphere Application Server 6.1/7.0

Perform this task only once per WebSphere Application Server 6.1/7.0 node, regardless of the number of WebSphere Application Server 6.1/7.0 instances that exist within the node.

ProcedureTo Enable Global Security for WebSphere Application Server 6.1/7.0

  1. Log in to the WebSphere Application Server 6.1/7.0 Administration Console.

  2. Navigate to Global security page:

    1. Expand the Security node.

    2. Click “Secure administration, applications, and infrastructure”. A new page opens.

      For WebSphere Application Server 7.0, click “Global Security”.

  3. Check the “Enable administrative security” checkbox.

  4. Make sure that “Enable application security” is also checked.

  5. Optionally, enable “Java 2 security” on the same page.

  6. Click Apply.

  7. Click “Save directly to the master configuration”.

Granting Access to the WebSphere Application Server 6.1/7.0 Administration Console

ProcedureTo Grant Access to the WebSphere Application Server 6.1/7.0 Administration Console

  1. Log in to the WebSphere Application Server 6.1/7.0 Administration Console.

  2. Expand the Users and Groups node.

  3. Click “Administrative Group Roles”. A new page opens.

  4. Click the Add button. A new page opens.

    1. In the “Group name” field, enter wasadmingroup, which was defined earlier.

      For WebSphere Application Server 7.0:

      • Select “Map Groups As Specified Below”.

      • In the “Search string” field, enter wasadmingroup, and then click Search.

      • In the “Available” field, find and select “id=wasadmingroup,ou=group,ROOT_SUFFIX@AmRealm”.

      • Click the right arrow button to add the results into the “Mapped to role” field.

    2. In the “Role(s)” field, select “Administrator”.

    3. Click OK and return to the “Administrative Group Roles” page.

  5. Click “Save directly to the master configuration”.

Setting the Application Logout URI For the IBM Console

ProcedureTo Set the Application Logout URI for the IBM Console

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control and then the name of the realm.

  3. Click Agents, J2EE, and then the name of the agent profile.

  4. Click Application.

  5. Under Application Logout URI, enter the following values:

    • Map Key: ibm/console

    • Corresponding Map Value: /ibm/console/logout.do

    • Click Add and then Save.

    The corresponding property is: .

    com.sun.identity.agents.config.logout.uri[ibm/console] = /ibm/console/logout.do

    This property is hot-swappable, so you do not need to restart the OpenSSO Enterprise web container instance.

Installing the Agent Filter for the WebSphere Application Server 6.1/7.0 Administration Console

The procedures that you have performed up to this point enable the Trust Association Interceptor to protect the Administration Console while users log in and establish the correct principal. However, the Trust Association Interceptor cannot trap logout events or enforce URL policies. The agent filter allows the enforcement of coarse grained URL policies defined within OpenSSO Enterprise to further control the access to protected resources on the WebSphere Application Server 6.1/7.0 Administration Console.

Therefore, you must add the agent filter to the web.xml file, as described in the following steps to protect the Administration Console. Without the filter element, you can log in to the Administration Console and perform normal operations, but the logout button will not function.

Note –

The agent filter should be the last filter executed in sequence. Therefore, ensure that you insert the agent filter after all other filters in the web.xml file.

ProcedureTo Install the Agent Filter for the WebSphere Application Server 6.1/7.0 Administration Console

  1. Locate the web.xml file for the WebSphere Application Server 6.1/7.0 instance.

    For example:

    DeployContainer-base/profiles/profile name/config/cells/cell
name/applications/isclite.ear/deployments/isclite/isclite.war/WEB-INF/

    where DeployContainer-base represents the directory where the WebSphere Application Server 6.1/7.0 instance was installed.

  2. Back up the web.xml file.

  3. Add the agent filter to the web.xml file.

    Ensure that the agent filter you add is the last filter to be executed in sequence. The example shows an excerpt of the web.xml file before the agent filter is added:

    <filter>
     <filter-name>WSCUrlFilter</filter-name>
     <filter-class>com.ibm.ws.console.core.servlet.WSCUrlFilter</filter-class>
</filter>
<filter-mapping>
     <filter-name>WSCUrlFilter</filter-name>
     <servlet-name>action</servlet-name>
</filter-mapping>
<filter-mapping>
	<filter-name>WSCUrlFilter</filter-name>
     <url-pattern>/federatedlogoff</url-pattern>
</filter-mapping>

    The example shows the agent filter in bold text:


    <filter>
     <filter-name>WSCUrlFilter</filter-name>
     <filter-class>com.ibm.ws.console.core.servlet.WSCUrlFilter</filter-class>
</filter>
<filter>
     <filter-name>Agent</filter-name>
     <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>

<filter-mapping>
     <filter-name>WSCUrlFilter</filter-name>
     <servlet-name>action</servlet-name>
</filter-mapping>
<filter-mapping>
	<filter-name>WSCUrlFilter</filter-name>
     <url-pattern>/federatedlogoff</url-pattern>
</filter-mapping>

<filter-mapping>
    <filter-name>Agent</filter-name>
    <url-pattern>/*</url-pattern>
 </filter-mapping>

  4. Restart the WebSphere Application Server 6.1/7.0 web container instance.

Allowing Access to the WebSphere Application Server 6.1/7.0 Administration Console

This task involves creating the corresponding URL policies in the OpenSSO Enterprise Console so that a specific user or group has access to the WebSphere Application Server 6.1/7.0 Administration Console.

ProcedureTo Allow Access to the WebSphere Application Server 6.1/7.0 Administration Console

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Create URL policies that provide the appropriate subjects with access to the WebSphere Application Server 6.1/7.0 Administration Console.

    Ensure that you give access to both HTTP and HTTPS based administration URLs. For example, you might allow the wasadmingroup access to the WebSphere Application Server 6.1/7.0 Administration Console by setting the following URL patterns:

    • http://host1.subexample.example.com:9060/*

    • https://host1.subexample.example.com:9043/*

    • http://host1.subexample.example.com:9060/*?*

    • https://host1.subexample.example:9043/*?*

    In this example, the WebSphere Application Server 6.1/7.0 Administration Console is running with the HTTP protocol on port 9060 and the HTTPS protocol on port 9043. All other changes to the agent configuration to trap logout events have already been configured by the agent installer. Note that the agent is configured in the most restrictive mode ALL at this point.

Verifying Access to the WebSphere Application Server 6.1/7.0 Administration Console

This task involves verifying that the previous tasks were performed properly and that the subjects assigned access to the WebSphere Application Server 6.1/7.0 Administration Console can access the console.

ProcedureTo Verify Access to the WebSphere Application Server 6.1/7.0 Administration Console

  1. Start the WebSphere Application Server 6.1/7.0 instance that you just configured.

  2. Run the WebSphere Application Server 6.1/7.0 agent in message mode.

  3. Log in to the WebSphere Application Server 6.1/7.0 Administration Console as a user who belongs to the WebSphere administrative group. For example: wasadmin

  4. If the user is properly redirected to OpenSSO Enterprise, enter the user name and password for any user assigned to the wasadmingroup in OpenSSO Enterprise.

    If you are allowed access, you should be redirected to the WebSphere Application Server 6.1/7.0 Administration Console.

  5. Perform normal operations in the WebSphere Application Server 6.1/7.0 Administration Console.

  6. Click logout.

    You should be redirected to the OpenSSO Enterprise Console.

Deploying the Agent Application

The agent application (agentapp.war) is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support.

ProcedureTo Deploy the Agent Application

  1. The agent application (agentapp.war) is bundled with the websphere_v61_agent_3.zip distribution file and is available as follows after you unzip the file:

    PolicyAgent-base/etc/agentapp.war

  2. Deploy agentapp.war on the WebSphere Application Server 6.1/7.0 instance using the WebSphere Application Server 6.1/7.0 administration console or deployment command.

    Important: You must use the same deployment URI that you specified for the “Agent URL” prompt during the agent installation. For example, if you accepted the default value (/agentapp) as the deployment URI for the agent application, use this same URI to deploy agentapp.war.

Configuring Applications Protected by the WebSphere Application Server/Portal Server Agent

Installing the Agent Filter for a Deployed Application on the WebSphere Application Server/Portal Server Agent

To install the agent filter, modify the deployment descriptor of each application that you want to protect.

ProcedureTo Install the Agent Filter for the WebSphere Application Server/Portal Server Agent

  1. Ensure that the application you want to protect is not currently deployed on WebSphere Application Server 6.1/7.0.

    If the application is deployed, undeploy it before continuing.

  2. Backup the application's web.xml file before you modify the descriptors.

    The backup copy can be useful if you need to uninstall the agent.

  3. Edit the application's descriptors in the web.xml file:

    1. Set the <DOCTYPE> element as shown in the following example:


      <!DOCTYPE web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

      Note: WebSphere Application Server/Portal Server supports the Java Servlet specification version 2.4. Version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation.

    2. Add the <filter> elements to the deployment descriptor.

      Specify the agent filter as the first <filter> element and the agent filter mapping as the first <filter-mapping> element. For example:


      <web-app>
...
    <filter>
        <filter-name>Agent</filter-name>
        <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
    </filter>
    <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>
...
</web-app>

  4. Deploy (or redeploy) the application on the WebSphere Application Server 6.1/7.0 web container.

    The agent filter is then added to the application.

Next Steps

You can also protect an application with Java EE declarative security. To learn more about protecting your application with Java EE declarative security, consider Deploying the Java EE Policy Agent Sample Application.