Deployment Example 1: Access Manager 7.1 Load Balancing, Distributed Authentication UI, and Session Failover

9.2.1 Installing Web Container 2 and Web Policy Agent 2 on Protected Resource 2

In this section, you install Sun Java System Web Server and a web policy agent on the ProtectedResource–2 host machine. Use the following list of procedures as a checklist.

  1. To Create an Agent Profile for Web Policy Agent 2

  2. To Install Sun Java System Web Server as Web Container 2 on Protected Resource 2

  3. To Install and Configure Web Policy Agent 2 on Protected Resource 2

  4. To Import the Certificate Authority Root Certificate into the Web Server 2 Keystore

  5. To Configure Policy for Web Policy Agent 2 on Protected Resource 2

  6. To Verify that Web Policy Agent 2 is Working Properly

ProcedureTo Create an Agent Profile for Web Policy Agent 2

You create an agent profile in Access Manager to store authentication and configuration information that will be used by the policy agent to authenticate itself to Access Manager. Creating an agent profile also creates a custom user. The policy agent will, by default, use the account with the user identifier UrlAccessAgent to authenticate to Access Manager.


Note –

Creating an agent profile is not a requirement for web policy agents. You can use the agent's default values and not change the user name; however, in certain cases, you might want to change these default values. For example, if you want to audit the interactions between multiple agents and the Access Manager server, you want be able to distinguish one agent from another. This would not be possible if all the agents used the same default agent user account. For more information, see the Sun Java System Access Manager Policy Agent 2.2 User’s Guide.


  1. Access http://AccessManager-1.example.com:1080/amserver/UI/Login from a web browser.

  2. Log in to the Access Manager console as the administrator.

    User Name:

    amadmin

    Password:

    4m4dmin1

  3. Under the Access Control tab, click example, the top-level Realm Name.

  4. Click the Subjects tab.

  5. Click the Agents tab.

  6. Click New to create a new agent profile.

  7. On the resulting page, enter the following and click OK.

    ID

    webagent-2

    Password:

    web4gent2

    Password Confirm

    web4gent2

    Device State

    Choose Active.

    The new agent webagent-2 is displayed in the list of agent users.

  8. Log out of the console.

ProcedureTo Install Sun Java System Web Server as Web Container 2 on Protected Resource 2

Download the Sun Java System Web Server bits and install the software on the ProtectedResource–2 host machine.

  1. As a root user, log into the ProtectedResource–2 host machine.

  2. Install required patches if necessary.

    Results for your machines might be different. Read the latest version of the Web Server 7.0 Release Notes to determine if you need to install patches and, if so, what they might be. In this case, the Release Notes indicate that based on the hardware and operating system being used, patch 117461–08 is required.

    1. Run patchadd to see if the patch is installed.


      # patchadd -p | grep 117461–08
      

      No results are returned which indicates that the patch is not yet installed on the system.

    2. Make a directory for downloading the patch you need and change into it.


      # mkdir /export/patches
      # cd /export/patches
      
    3. Download the patches.

      You can search for patches directly at http://sunsolve.sun.com. Navigate to the PatchFinder page, enter the patch number, click Find Patch, and download the appropriate patch.


      Note –

      Signed patches are downloaded as JAR files. Unsigned patches are downloaded as ZIP files.


    4. Unzip the patch file.


      # unzip 117461–08.zip
      
    5. Run patchadd to install the patches.


      # patchadd /export/patches/117461–08
      
    6. After installation is complete, run patchadd to verify that the patch was added successfully.


      # patchadd -p | grep 117461–08
      

      In this example, a series of patch numbers are displayed, and the patch 117461–08 is present.

  3. Create a directory into which you can download the Web Server bits and change into it.


    # mkdir /export/ws7
    # cd /export/ws7
    
  4. Download the Sun Java System Web Server 7.0 software from http://www.sun.com/download/products.xml?id=45ad781d.

    Follow the instructions on the Sun Microsystems Product Downloads web site for downloading the software. In this example, the software was downloaded to the /export/ws7 directory.


    # ls -al
    
    total 294548
    drwxr-xr-x   2 root     root         512 Aug  7 13:23 .
    drwxr-xr-x   3 root     sys          512 Aug  7 13:16 ..
    -rw-r--r--   1 root     root     150719523 Aug  7 13:24 sjsws-7_0-solaris-sparc.tar.gz
    
  5. Unpack the Web Server bits.


    # gunzip sjsws-7_0-solaris-sparc.tar.gz
    # tar xvf sjsws-7_0-solaris-sparc.tar
    
  6. Run setup.


    # ./setup --console
    
  7. When prompted, provide the following information.


    You are running the installation program 
    for the Sun Java System Web Server 7.0.
    ...
    The installation program pauses as questions 
    are presented so you can read the 
    information and make your choice.  
    When you are ready to continue, press Enter.

    Press Enter. Continue to press Enter when prompted. 


    Have you read the Software License 
    Agreement and do you accept all the terms?

    Enter yes.


    Sun Java System Web Server 7.0 
    Installation Directory [/sun/webserver7]

    Enter /opt/SUNWwbsvr


    Specified directory /opt/SUNWwbsvr 
    does not exist.  Create Directory? [Yes/No]				

    Enter yes.


    Select Type of Installation
    
    1. Express
    2. Custom
    3. Exit
    What would you like to do? [1]

    Enter 2.


    Component Selection
    
    1. Server Core
    2. Server Core 64-biy Binaries
    3. Administration Command Line Interface
    4. Sample Applications
    5. Language Pack
    Enter the comma-separated list [1,2,3,4,5]

    Enter 1,3,5.


    Java Configuration
    1. Install Java Standard Edition 1.5.0_09
    2. Reuse existing Java SE 1.5.0_09 or greater
    3. Exit
    What would you like to do? [1]

    Enter 1.


    Administrative Options
    1. Create an Administration Server and a 
       Web Server Instance
    2. Create an Administration Node
    Enter your option. [1]

    Enter 1.


    Start servers during system startup. [yes/no]

    Enter no.


    Host Name [ProtectedResource-2.example.com]

    Accept the default value. 


    SSL Port [8989]

    Accept the default value. 


    Create a non-SSL Port? [yes/no]

    Enter no.


    Runtime User ID [webservd]

    Enter root.


    Administrator User Name [admin]

    Accept the default value. 


    Administrator Password:

    Enter web4dmin.


    Retype Password:

    Enter web4dmin.


    Server Name [ProtectedResource-2.example.com]

    Accept the default value. 


    Http Port [8080]

    Enter 1080.


    Document Root Directory [/opt/SUNWwbsvr/
    https-ProtectedResource-2.example.com/docs]

    Accept the default value. 


    Ready To Install
    1. Install Now
    2. Start Over
    3. Exit Installation
    What would you like to do?

    Enter1.

    When installation is complete, the following message is displayed:


    Installation Successful.
  8. Start the Web Server administration server.


    # cd /opt/SUNWwbsvr/admin-server/bin
    # ./startserv
    
    server not running
    Sun Java System Web Server 7.0 B12/04/2006 10:15
    info: CORE3016: daemon is running as super-user
    info: CORE5076: Using [Java HotSpot(TM) Server VM, Version 1.5.0_09] 
      from [Sun M icrosystems Inc.] 
    info: WEB0100: Loading web module in virtual server [admin-server] at 
      [/admingui ]
    info: WEB0100: Loading web module in virtual server [admin-server] at 
      [/jmxconne ctor]
     info: HTTP3072: admin-ssl-port: https://protectedresource-2.example.com:8989 
      ready to accept requests
    info: CORE3274: successful server startup
  9. Run netstat to verify that the port is open and listening.


    # netstat -an | grep 8989
    
    *.8989               *.*                0      0 49152      0 LISTEN
  10. (Optional) Login to the Web Server administration console at https://protectedresource-2.example.com:8989.

    Username

    admin

    Password

    web4dmin

    You should see the Web Server console.

  11. (Optional) Log out of the Web Server console.

  12. Start the Protected Resource 2 Web Server instance.


    # cd /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/bin
    # ./startserv
    
    server not running
    Sun Java System Web Server 7.0 B12/04/2006 10:15
    info: CORE3016: daemon is running as super-user
    info: CORE5076: Using [Java HotSpot(TM) Server VM, 
       Version 1.5.0_09] from [Sun Microsystems Inc.]
    info: HTTP3072: http-listener-1: http://ProtectedResource-2.example.com:1080 
       ready to accept requests
    info: CORE3274: successful server startup
  13. Run netstat to verify that the port is open and listening.


    # netstat -an | grep 1080
    
    *.1080               *.*                0      0 49152      0 LISTEN
  14. Access the Protected Resource 2 instance at https://ProtectedResource-2.example.com:1080 using a web browser.

    You should see the default Web Server index page.

  15. Log out of the ProtectedResource–2 host machine.

ProcedureTo Install and Configure Web Policy Agent 2 on Protected Resource 2


Caution – Caution –

Due to a known problem with this version of the Web Policy Agent, you must start an X-display session on the server host using a program such as Reflections X or VNC, even though you use the command-line installer. For more information about this known problem, see On UNIX-based machines, all web agents require that the X11 DISPLAY variable be set properly. in Sun Java System Access Manager Policy Agent 2.2 Release Notes.


  1. As a root user, log into the ProtectedResource–2 host machine.

  2. Ensure that your system is properly patched.

    This should have been done in To Install Sun Java System Web Server as Web Container 2 on Protected Resource 2.

  3. Create a directory into which you can download the Web Server agent bits and change into it.


    # mkdir /export/WebPA2
    # cd /export/WebPA2
    
  4. Download the web policy agent for Web Server from http://www.sun.com/download/.


    # ls -al
    
    total 294548
    drwxr-xr-x   2 root     root         512 Aug  7 13:23 .
    drwxr-xr-x   3 root     sys          512 Aug  7 13:16 ..
    -rw-r--r--   1 root     root     150719523 Aug  7 13:24 sjsws_v70_SunOS_agent.zip
    
  5. Unzip the downloaded file.


    # unzip sjsws_v70_SunOS_agent.zip
    
  6. Change the permissions for the resulting agentadmin binary.


    # cd /export/WebPA2/web_agents/sjsws_agent/bin
    # chmod +x agentadmin
    
  7. Verify that crypt_util has execute permission before running the installer.


    # cd /export/WebPA2/web_agents/sjsws_agent/bin
    # chmod +x crypt_util
    
  8. Create a temporary file for the password that will be required during agent installation.


    # echo web4gent2 > /export/WebPA2/pwd.txt
    # cat /export/WebPA2/pwd.txt
    
  9. Run the agent installer.


    # ./agentadmin --install
    
  10. When prompted, do the following.


    Do you completely agree with all the terms and 
    conditions of this License Agreement (yes/no): [no]:

    Type yes and press Enter.


    *********************************************
    Welcome to the Access Manager Policy Agent for 
    Sun Java System Web Server If the Policy Agent is 
    used with Federation Manager services, User needs to
    enter information relevant to Federation Manager.
    ***************************************************
     

    Enter the complete path to the directory 
    which is used by Sun Java System Web Server to 
    store its configuration Files. This directory 
    uniquely identifies the Sun Java System Web Server 
    instance that is secured by this Agent.
    [ ? : Help, ! : Exit ]
    Enter the Sun Java System Web Server Config 
    Directory Path [/var/opt/SUNWwbsvr7/
      https-ProtectedResource-2.example.com/config]:

    Type /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/config and press Enter.


    Enter the fully qualified host name of 
    the server where Access Manager Services are 
    installed. [ ? : Help, < : Back, ! : Exit ]
    Access Manager Services Host:

    Type LoadBalancer-3.example.com and press Enter.


    Enter the port number of the Server that 
    runs Access Manager Services.
    [ ? : Help, < : Back, ! : Exit ]
    Access Manager Services port [80]:

    Type 9443 and press Enter.


    Enter http/https to specify the protocol 
    used by the Server that runs Access Manager 
    services. [ ? : Help, < : Back, ! : Exit ]
    Access Manager Services Protocol [http]:

    Type https and press Enter.


    Enter the Deployment URI for Access Manager 
    Services. [ ? : Help, < : Back, ! : Exit ]
    Access Manager Services Deployment URI [/amserver]:

    Press Enter to accept the default /amserver.


    Enter the fully qualified host name on which 
    the Web Server protected by the agent is installed.
    [ ? : Help, < : Back, ! : Exit ]
    Enter the Agent Host name:

    Type ProtectedResource-2.example.com and press Enter.


    Enter the preferred port number on which the 
    Web Server provides its services.
    [ ? : Help, < : Back, ! : Exit ]
    Enter the port number for Web Server instance [80]:

    Type 1080 and press Enter.


    Select http or https to specify the protocol 
    used by the Web server instance that will be protected 
    by Access Manager Policy Agent.
    [ ? : Help, < : Back, ! : Exit ]
    Enter the Preferred Protocol for Web Server 
    instance [http]:

    Press Enter to accept the default http.


    Enter a valid Agent profile name. Before 
    proceeding with the agent installation, please ensure 
    that a valid Agent profile exists in Access Manager.
    [ ? : Help, < : Back, ! : Exit ]
    Enter the Agent Profile name [UrlAccessAgent]:

    Type webagent-2 and press Enter.


    Enter the path to a file that contains the 
    password to be used for identifying the Agent.
    [ ? : Help, < : Back, ! : Exit ]
    Enter the path to the password file:

    Type /export/WebPA2/pwd.txt and press Enter.


    -----------------------------------------
    SUMMARY OF YOUR RESPONSES
    -----------------------------------------------
    Sun Java System Web Server Config Directory :
    /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/
      config
    Access Manager Services Host : LoadBalancer-3.example.com
    Access Manager Services Port : 9443
    Access Manager Services Protocol : https
    Access Manager Services Deployment URI : /amserver
    Agent Host name : ProtectedResource-2.example.com
    Web Server Instance Port number : 1080
    Protocol for Web Server instance : http
    Agent Profile name : webagent-2
    Agent Profile Password file name : 
      /export/WebPA2/pwd.txt
    
    Verify your settings above and decide from the choices 
       below.
    1. Continue with Installation
    2. Back to the last interaction
    3. Start Over
    4. Exit
    Please make your selection [1]:

    Type 1 and press Enter.


    Creating directory layout and configuring Agent 
    file for Agent_001 instance ...DONE.
    
    Reading data from file /export/WebPA2/pwd.txt and 
    encrypting it ...DONE.
    
    Generating audit log file name ...DONE.
    
    Creating tag swapped AMAgent.properties file for 
    instance Agent_001 ...DONE.
    
    Creating a backup for file
    /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/
       config/obj.conf ...DONE.
    
    Creating a backup for file
    /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/
       config/magnus.conf ...DONE.
    
    Adding Agent parameters to
    /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/
       config/magnus.conf file ...DONE.
    
    Adding Agent parameters to
    /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/
       config/obj.conf file ...DONE.
    
    
    SUMMARY OF AGENT INSTALLATION
    -----------------------------
    Agent instance name: Agent_001
    Agent Configuration file location:
    /export/WebPA2/web_agents/sjsws_agent/Agent_001/
      config/AMAgent.properties
    Agent Audit directory location:
    /export/WebPA2/web_agents/sjsws_agent/Agent_001/
      logs/audit
    Agent Debug directory location:
    /export/WebPA2/web_agents/sjsws_agent/Agent_001/
      logs/debug
    
    Install log file location:
    /export/WebPA2/web_agents/sjsws_agent/logs/audit/
      install.log
    
    Thank you for using Access Manager Policy Agent
     

  11. Modify the AMAgent.properties file.


    Tip –

    Backup AMAgent.properties before you modify it.


    1. Change to the config directory.


      # cd /export/WebPA2/web_agents/sjsws_agent/Agent_001/config
      
    2. Set the values of the following properties as shown.

      com.sun.am.policy.am.login.url = https://LoadBalancer-3.
         example.com:9443/amserver/UI/Login?realm=users
      com.sun.am.load_balancer.enable = true
    3. Save the file and close it.

  12. Restart the Protected Resource 2 Web Server instance.


    # cd /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/bin 
    # ./stopserv; ./startserv
    
    server has been shutdown 
    Sun Java System Web Server 7.0 B12/04/2006 10:15 
    info: CORE3016: daemon is running as super-user info:
    CORE5076: Using [Java HotSpot(TM) Server VM, Version 1.5.0_09]
      from [Sun Microsystems Inc.] 
    info: HTTP3072: http-listener-1: http://ProtectedResource-2.example.com:1080
      ready to accept requests
  13. Log out of the ProtectedResource–2 host machine.

ProcedureTo Import the Certificate Authority Root Certificate into the Web Server 2 Keystore

The web policy agent on Protected Resource 2 connects to Access Manager through Load Balancer 3. The load balancer is SSL-enabled, so the agent must be able to trust the load balancer SSL certificate to establish the SSL connection. For this reason, import the root certificate of the Certificate Authority (CA) that issued the Load Balancer 3 SSL server certificate into the policy agent keystore.

Before You Begin

Import the same CA root certificate used in To Import a Certificate Authority Root Certificate on the Access Manager Load Balancer.

  1. As a root user, log into the ProtectedResource–2 host machine.

  2. Copy the CA root certificate into a directory.

    In this example, the file is /export/software/ca.cer.

  3. Import the CA root certificate into the Java keystore.


    # /opt/SUNWwbsvr/jdk/jre/bin/keytool -import -trustcacerts 
      -alias OpenSSLTestCA -file /export/software/ca.cer 
      -keystore /opt/SUNWwbsvr/jdk/jre/lib/security/cacerts -storepass changeit
    
    Owner: EMAILADDRESS=nobody@nowhere.com, CN=OpenSSLTestCA, OU=Sun,
    O=Sun,L=Santa Clara, ST=California C=US
    Issuer: EMAILADDRESS=nobody@nowhere.com, CN=OpenSSLTestCA, OU=Sun,
    O=Sun,L=Santa Clara, ST=California C=US
    Serial number: 97dba0aa26db6386
    Valid from: Tue Apr 18 07:66:19 PDT 2006 until: Tue Jan 13 06:55:19
    PST 2009
    Certificate fingerprints:
    MD5: 9f:57:ED:B2:F2:88:B6:E8:0F:1E:08:72:CF:70:32:06
    SHA1: 31:26:46:15:C5:12:5D:29:46:2A:60:A1:E5:9E:26:64:36:80:E4:70
    Trust this certificate: [no] yes
    Certificate was added to keystore.
  4. Verify that the CA root certificate was imported into the keystore.


    # /opt/SUNWwbsvr/jdk/jre/bin/keytool -list 
      -keystore /opt/SUNWwbsvr/jdk/jre/lib/security/cacerts 
      -storepass changeit | grep -i open
    
    openssltestca, Sep 10, 2007, trustedCertEntry,
  5. Restart the Protected Resource 2 Web Server instance.


    # cd /opt/SUNWwbsvr/https-ProtectedResource-2.example.com/bin
    # ./stopserv
    # ./startserv
    
    server has been shutdown
    Sun Java System Web Server 7.0 B12/04/2006 10:15
    info: CORE3016: daemon is running as super-user
    info: CORE5076: Using [Java HotSpot(TM) Server VM, 
    Version 1.5.0_09] from [Sun Microsystems Inc.]
    info: HTTP3072: http-listener-1: http://ProtectedResource-2.
    example.com:1080 ready to accept requests
    info: CORE3274: successful server startup
  6. Log out of the ProtectedResource–2 host machine.

ProcedureTo Configure Policy for Web Policy Agent 2 on Protected Resource 2

Use the Access Manager console to configure policy for Web Policy Agent 2. This policy will be used to verify that Web Policy Agent 2 is working properly. You will modify this policy later when we add a load balancer in front of it.

  1. Access http://AccessManager-1.example.com:1080/amserver/UI/Login from a web browser.

  2. Log in to the Access Manager console as the administrator.

    Username

    amadmin

    Password

    4m4dmin1

  3. Create a referral policy in the top-level realm.

    1. Under the Access Control tab, click the top-level realm, example.

    2. Click the Policies tab.

    3. Click Referral URL Policy for users realm.

    4. On the same page, in the Rules section, click New.

    5. On the resulting page, select URL Policy Agent (with resource name) as a Service Type and click Next.

    6. Provide the following information on the resulting page.

      Name:

      URL Rule for ProtectedResource-2

      Resource Name:

      http://ProtectedResource-2.example.com:1080/*

    7. Click Finish.

    8. Click Save.

    9. On the Edit Policy page, click Back to Policies.

      Under the Policies tab for the example realm, you should see the policy named Referral URL Policy for users realm with http://ProtectedResource-2.example.com:1080/* added in the list of protected resources.

  4. Create a policy in the users realm.

    The users realm was previously created in 7.2 Creating and Configuring a Realm for Test Users.

    1. Click the Access Control tab.

    2. Under Realms, click users.

    3. Click the Policies tab.

    4. Click New Policy.

    5. On the New Policy page, provide the following information:

      Name:

      URL Policy for ProtectedResource-2

      Active:

      Mark the Yes checkbox.

    6. On the same page, in the Rules section, click New.

    7. Select a Service Type for the rule and click Next.

      URL Policy Agent (with resource name) is the only choice.

    8. On the resulting page, provide the following information:

      Name:

      URL Rule for ProtectedResource-2

      Resource Name:

      Click http://ProtectedResource-2.example.com:1080/*, listed in the Parent Resource Name list, to add it to the Resource Name field.

      GET:

      Mark this checkbox, and select Allow.

      POST:

      Mark this checkbox, and select Allow.

    9. Click Finish.

  5. Create a new subject in the users realm for testing.

    1. On the New Policy page, in the Subjects section, click New.

    2. Select Access Manager Identity Subject as the subject type and click Next.

    3. Provide the following information on the resulting page.

      Name:

      Test Subject

      Filter:

      Choose User and click Search. Two users are added to the Available list.

      Available:

      In the list, select Test User1 and click Add.

    4. Click Finish.

  6. Back on the New Policy page, click Create.

    Under the Policies tab, you should see the policy named URL Policy for ProtectedResource-2.

  7. Log out of the console.

ProcedureTo Verify that Web Policy Agent 2 is Working Properly

  1. Access http://ProtectedResource-2.example.com:1080 from a web browser.

  2. Log in to Access Manager as testuser1.

    Username

    testuser1

    Password

    password

    You should see the default index page for Web Server 2 as testuser1 was configured in the test policy to be allowed to access Protected Resource 2.

  3. Log out and close the browser.

  4. Once again, access http://ProtectedResource-2.example.com:1080 from a web browser.


    Tip –

    If you are not redirected to the Access Manager login page for authentication, clear your browser's cache and cookies and try again.


  5. Log in to Access Manager as testuser2.

    Username

    testuser2

    Password

    password

    You should see the message, You're not authorized to view this page, (or Your client is not allowed to access the requested object) as testuser2 was not included in the test policy that allows access to Protected Resource 2.