test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Microsoft Internet Information Services (IIS) 6.0

Post-Installation Tasks for the IIS 6.0 Agent

Creating and Adding Logout URLs in a CDSSO Deployment

If Cross-Domain Single Sign-On (CDSSO) is enabled for the agent, the OpenSSO logout URL cannot clear the cookies in the agent domain, and you must create two logout pages as IIS 6.0 resources.

ProcedureTo Create the Logout URL Pages

  1. Create two logout URL pages as IIS 6.0 resources. For example: logout.html and logout2.html

  2. Store the logout URL pages in the doc directory of the IIS 6.0 instance. The default directory is C:\inetpub\wwwroot.

  3. Make sure you can access the logout URLs from a browser. For example:

    • http://agenthost.example.com:port/logout.html

    • http://agenthost.example.com:port/logout2.html

ProcedureTo Add the Logout URLs in the OpenSSO Console

  1. Login to the OpenSSO console as amadmin.

  2. Click Access Control, realm-name, Agents, and then the profile name for the IIS 6.0 agent.

  3. On the agent Edit page, click OpenSSO Services.

  4. Under Agent Logout URL, add the logout URLs. For example:

    • Logout URL: http://agenthost.example.com:port/logout.html

    • Logout Redirect URL: http://agenthost.example.com:port/logout2.html

  5. Click Save.

  6. On the agent Edit page, click Application.

  7. Add the same URLs as Not Enforced URLs:

    • http://agenthost.example.com:port/logout.html

    • http://agenthost.example.com:port/logout2.html

  8. Click Save.

Next Steps

The logout links in an application deployed on the IIS 6.0 instance should invoke the logout URL used in this procedure.

Using SSL With the IIS 6.0 Agent (Optional)

If you specify the https protocol for the OpenSSO Enterprise server URL during the IIS 6.0 agent installation, the agent is automatically configured and ready to communicate to the OpenSSO Enterprise server over Secure Sockets Layer (SSL). However, to ensure that the IIS 6.0 agent is configured for SSL communication to the server, follow these tasks:

Installing the OpenSSO Enterprise Root CA Certificate on the IIS 6.0 Agent

The root CA certificate that you install on the IIS 6.0 agent must be the same certificate that is installed on the OpenSSO Enterprise host server.

Sun provides the Certificate Database Tool, certutil.exe, in the IIS 6.0 agent distribution file, to manage the root CA certificate and the certificate database.

For information about using certutil.exe, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.

ProcedureTo Install the OpenSSO Enterprise Root CA Certificate on the IIS 6.0 Agent

  1. Obtain the root CA certificate file that is installed on the OpenSSO Enterprise host server. The following examples use root_ca.crt as the name for the root CA certificate file.

  2. On the IIS 6.0 server, locate the certutil.exe utility.

    After you unzip the IIS 6.0 agent distribution file, certutil.exe is available in the PolicyAgent-base\bin directory.

    For example: C:\Agents\web_agents\iis6_agent\bin\certutil.exe

  3. If necessary, create the certificate database directory and the certificate database in the PolicyAgent-base directory. For example:

    mkdir C:\Agents\web_agents\iis6_agent\cert
C:\Agents\web_agents\iis6_agent\bin certutil.exe -N -d ..\cert

    where cert is the name of the certificate database directory.

    When prompted, enter and confirm the password that will be used to encrypt your keys.

  4. Install the OpenSSO Enterprise root CA certificate in the database. For example:

    certutil.exe -A -n am_root_ca_cert -t "C,C,C" -d ..\cert -i ..\cert\root_ca.crt

    where:

    • am_root_ca_cert is the name of the OpenSSO Enterprise root CA certificate.

    • root_ca.crt is the binary root CA certificate request file.

  5. To verify that the root CA certificate is installed correctly, use certutil.exe with the -L option. For example:

    C:\Agents\web_agents\iis6_agent\bin certutil.exe -L -d ..\cert am_root_ca_cert

    You should see the name of the root CA certificate. For example:

    am_root_ca_cert                                              C,C,C

Disabling the Trust Behavior for the IIS 6.0 Agent

By default, the IIS 6.0 agent installed on a remote IIS 6.0 server trusts any server certificate presented over SSL by the OpenSSO Enterprise host. For the IIS 6.0 agent to perform certificate checking, you must disable this trust behavior.

ProcedureTo Disable the Trust Behavior for the IIS 6.0 Agent

  1. Find the IIS 6.0 agent's OpenSSOAgentBootstrap.properties file in the agent's \config directory. For example:

    C:\Agents\web_agents\iis6_agent\config\OpenSSOAgentBootstrap.properties

  2. In the OpenSSOAgentBootstrap.properties file, set the SSL-related properties, depending on your specific deployment.

    Note: These properties have new names for version 3.0 web agents.

    • Disable the option to trust the server certificate sent over SSL by the OpenSSO Enterprise host server:

      com.sun.identity.agents.config.trust.server.certs = false

    • Specify the certificate database directory.

      com.sun.identity.agents.config.sslcert.dir = path-to-cert-database

      For example:

      com.sun.identity.agents.config.sslcert.dir = C:/Agents/web_agents/iis6_agent/cert

    • If the certificate database directory has multiple certificate databases, set the following property to the prefix of the database you want to use. For example:

      com.sun.identity.agents.config.certdb.prefix = prefix-

    • Specify the certificate database password:

      com.sun.identity.agents.config.certdb.password = password

    • Specify the certificate database alias:

      com.sun.identity.agents.config.certificate.alias = alias-name

  3. Save the changes to the OpenSSOAgentBootstrap.properties file.

    The agent uses information in the OpenSSOAgentBootstrap.properties file to start and initialize itself and to communicate with OpenSSO Enterprise server.

  4. Restart IIS 6.0 using the iisreset command.

Setting the Post Data Preservation Load Balancer Cookie (Optional)

If a load balancer is configured in front of multiple agent instances and post data preservation is enabled in these agent instances, you must specify the post data preservation load balancer cookie by setting the following property in the OpenSSO Console:

com.sun.identity.agents.config.postdata.preserve.lbcookie

This property specifies the name and value of the sticky cookie used by the load balancer to route the incoming request.

ProcedureTo Set the Post Data Preservation Load Balancer Cookie

  1. Login to the OpenSSO Console as amadmin.

  2. Click Access Control, realm-name, Agents, and then the profile name for the IIS 6.0 agent.

  3. Click Advanced.

  4. Scroll down to Custom Properties and add the com.sun.identity.agents.config.postdata.preserve.lbcookie property. For example:

    com.sun.identity.agents.config.postdata.preserve.lbcookie = palbcookie=01

  5. Click Save.

Ignoring the Path for Not Enforced URLs (Optional)

The com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list property indicates whether the path information and query should be removed from the request URL before it is compared with not-enforced URLs, when those URLs have a wildcard (*) character.

For security reasons, this property should be set to true, to avoid certain situations. For example, if a not-enforced URL such as http://host/*.gif exists, someone can access http://host/index.html by using the request URL http://host/index.html/hack.gif.

The default value for com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list is true. If necessary, you can set is property in the OpenSSO Console.

ProcedureTo Ignore the Path for Not Enforced URLs

  1. Login to the OpenSSO Console as amadmin.

  2. Click Access Control, realm-name, Agents, and then the profile name for the IIS 6.0 agent.

  3. Click Advanced.

  4. Scroll down to Custom Properties and add the following property:

    com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list=true

  5. Click Save.

Changing the Password for an Agent Profile (Optional)

This task is optional. After you install the agent, you can change the agent profile password, if required for your deployment.

ProcedureTo Change the Password for an Agent Profile

  1. On the OpenSSO Enterprise server:

    1. Login into the Administration Console.

    2. Click Access Control, realm-name, Agents, Web, and then the name of the agent you want to configure.

      The Console displays the Edit page for the agent profile.

    3. Enter and confirm the new unencrypted password.

    4. Click Save.

  2. On the server where the IIS 6.0 agent is installed:

    1. In the agent profile password file, replace the old password with the new unencrypted password.

    2. Change to the PolicyAgent-base\bin directory. For example:

      cd C:\Agents\web_agents\iis6_agent\bin

    3. Encrypt the new password using cryptit.exe.

      cryptit.exe C:\tmp\IIS6Agentpw.txt encryption-key

      where encryption-key can be either the existing key value from the com.sun.identity.agents.config.key property in the IIS 6.0 agent's OpenSSOAgentBootstrap.properties file or a new encryption key value. A new key value must be a minimum of eight alphanumeric characters.

      The cryptit.exe program returns the new encrypted password. For example:

      /54GwN432q+MEnfh/AHLMA==

    4. In the IIS 6.0 agent's OpenSSOAgentBootstrap.properties file, set the following properties, as needed:

      • Set the following property to the new encrypted password from the previous step. For example:

        com.sun.identity.agents.config.password=/54GwN432q+MEnfh/AHLMA==

      • If you specified a new encryption key value in the previous step, set the following property to this new key value:

        com.sun.identity.agents.config.key=new-key-value

    5. Restart the IIS 6.0 server.