22.4 Managing Host Identifiers

Administrators can create, modify, and remove host identifiers manually.

• About Host Identifiers

• About Virtual Web Hosting

• Host Identifier Page

• Creating a Host Identifier

• Searching for a Host Identifier Definition

• Viewing or Editing a Host Identifier Definition

• Deleting a Host Identifier Definition

22.4.1 About Host Identifiers

Access Manager policies protect resources on computer hosts. Within Access Manager, the computer host is specified independently using a host identifier.

Table 22-3 illustrates the different host names under which a Web server might be accessible to employees. Creating a single Host Identifier using all of these names allows you to define a single set of policies to appropriately protect the application, regardless of how the user accesses it.

Table 22-3 Host Identifiers Examples

Sample Host Identifier	Description
hrportal.intranet.company.com	A friendly name employees can remember. This is a load-balanced proxy, and requests to this could actually utilize one of several servers hosting the HR application.
hr-sf-02.intranet.company.com	A single machine hosting the application, which can be accessed directly.
hrportal.company.com	The same application is also accessible externally to the corporate firewall, primarily for use by ex-employees to check benefits, 401k info, and so on. This is also a load-balanced reverse proxy.

Based on a defined host identifier, Administrators can add specific resources to an Application Domain and apply policies to protect those resources.

Registered Agents protect all requests that match the addressing methods defined for the host identifier used in a policy. A request sent to any address on the list is mapped to the official host name and Access Manager can apply the policies that protect the resource and OAM can apply the policies that protect the resource.

A host identifier is automatically created when an Agent (and application) are registered using either the Oracle Access Management Console or the remote registration tool. Administrators can manually add a host identifier if an application and resources exist on a host that does not have a mapped host identifier. Also, Oracle Access Management Administrators can modify an existing host identifier to add in the new host name variations. For instance, adding another proxy Web server with a different host name requires a new host name variation.

For more information, see:

• Host Identifier Usage

• Host Identifier Guidelines

• Host Identifier Variations

22.4.1.1 Host Identifier Usage

At design time, the host identifier can be used while defining which resources belong to a specific Application Domain. Resources are scoped using their host identifier (HTTP) or type (non-HTTP). This combination uniquely identifies them across Access Manager.

Note:

Each resource should be unique across all Application Domains; each resource and host identifier combination must be unique across all Application Domains.

Runtime Usage

At run time, Web server host information in the access query from an OAM Agent is mapped to a host identifier and associated with the resource that is being accessed by a user. The OAM Agent obtains the Web server host information in one of two ways:

• If the Preferred Host parameter is configured for virtual Web hosting support (see"About Virtual Web Hosting"), Web server host information for the given request is obtained from the Web server.

• If the Preferred Host parameter directly specifies the Web server host information, it is always used irrespective of the Web server's own host information.

This allows for the Resources to be specified in terms of logical host names in their Host Identifiers, instead of the host names matching the present deployment of the Web server.

For instance, a user accessing aseng-wiki, would enter:

http://example-wiki.uk.example.com/wikiexample

Here, wikiexample is the resource URL and example-wiki.uk.example.com is the host. Matching this host and port (port is 80) provides the host identifier.

Preferred Host

Web server host information is generally acquired by setting the Preferred Host string of the OAM Agent. If the Agent is actively protecting multiple virtual hosts, this string can be set to server_name to ensure that the actual request hostname is correctly picked up from the Web server's request object. For more information, see "About Virtual Web Hosting"

Authenticating Hosts and Challenge Redirect in Authentication Schemes

When a user attempts to access a protected resource URL, she is redirected to the server specified in the Challenge Redirect field of the authentication scheme. If the authentication challenge is to be processed by another host, the name of that host must be defined to be available in the Host Identifiers list. For example, if a user is redirected to an SSL-enabled server for authentication, that server must be defined as a host identifier.

Note:

If you enter a host name in the Challenge Redirect field of an authentication scheme, it must be defined as a Host Identifier.

22.4.1.2 Host Identifier Guidelines

Each host identifier can be defined to represent one or more Web server hosts.

Following are several important guidelines for host identifiers:

• Each host name must be unique.

• Each host name:port pair must be unique.

• Each host name:port pair must belong to only one host identifier.

• Each host name:port pair must match the end user's entry exactly.

• A Host Identifier name cannot match a non-HTTP Resource Type name (and vice versa).

• Each resource and host identifier combination must be unique across all Application Domains.

For more information, see "Host Identifier Variations".

22.4.1.3 Host Identifier Variations

Host identifiers are used to simplify the identification of a Web server host by defining all possible hostname variations. Host identifiers consist of a list of all URL addressing methods. A host identifier must be configured for each Web site or virtual Web site that you want to protect with Access Manager.

You can identify Web server hosts to Access Manager in various ways, for example, by providing a computer name or an IP address. The following are examples of how the same host can be addressed:

• example.com

• example.com:80

• www.example.com

• www.example.com:80

• 216.200.159.58

• 216.200.159.58:80

22.4.2 About Virtual Web Hosting

You can install a Webgate on a Web server that contains multiple Web site and domain names. The Webgate must reside in a location that enables it to protect all of the Web sites on that server.

The information here is the same for both 11g and 10g Webgates.

The virtual Web hosting feature of many Web servers enables you to support multiple domain names and IP addresses that each resolve to their unique subdirectories on a single virtual server. For example, you can host abc.com and def.com on the same virtual server, each with its own domain name and unique site content. You can have name-based or IP-based virtual hosting.

A virtual host referees the situation where the same host has multiple sites being served either based on multiple NIC cards (IP based) or multiple names (for example, abc.com and def.com resolving to same IP).

Consider a case where you have two virtual hosts configured on an OHS Server acting as reverse proxy to OAM Server, as follows:

• One virtual host is configured in two-way SSL mode

• One virtual host configured in non-SSL mode

Suppose there are two resources protected with different authentication schemes and Application Domains:

• /resource1 is protected by a X509Scheme with a Challenge URL (to define the credential collection URL) of https://sslvhost:port/

  When the user accesses /resource1 he is redirected to the OHS Server on the SSL port for authentication and is asked for the X.509 Certificate.

• /resource2 is protected by a LDAPScheme on the second virtual host with a Challenge Redirect of http://host:port/

  When user accesses /resource2 he is redirected to second virtual host which is in non-SSL mode (or in one way SSL mode if required). The Login form for LDAP authentication is displayed.

Note:

Your deployment can support X.509 and Form authentication with 10g mod_osso. However, mod_osso can be configured for only one SSO Server. In this case, the Agent redirects to Access Manager on the non-SSL virtual host. The credential collector checks the Authentication Scheme's Challenge URL parameter for the resource and redirects back to the HTTPS virtual host for X509 authentication.

22.4.2.1 Placing a Webgate Behind a Reverse Proxy

You can use 10g Webgates with reverse proxies for Access Manager.

The benefits and pitfalls of this strategy are discussed here.

Benefits:

• All Web content can be protected from a single logical component as long as all requests go through the proxy.

  This is true even for platforms that are not supported by Access Manager. If you have different types of Web servers (for example, iPlanet, Apache, and so on) on different platforms (for example, Windows XP, Linux, and so on), all content on these servers can be protected. A reverse proxy can be a workaround for unsupported Web servers, eliminating the need to write custom Access Clients for unsupported Web servers and on platforms that do not have Webgate support, for example, MacOS.

• A reverse proxy offers architecture flexibility.

  Reverse proxies can allow deployments to expose an application that is available on the intranet to the extranet. Or applications that are available on the extranet can be exposed to the intranet. This can be done without any changes to the application that is already deployed.

• You only need to install a separate Webgate on the reverse proxy, rather than on every Web server.

  This allows for a single management point and can help with manageability of the system. You can manage the security of all of the Web servers through the reverse proxy without establishing a footprint on the other Web Servers.

Pitfalls: The main pitfall of using a proxy is the extra work involved in setup. If you deploy the Webgate on a Web server that is behind a reverse proxy, the following are configuration requirements:

• Ensure that any Web server that uses the reverse proxy for authentication only accepts requests from the reverse proxies.

  This will also require that Webgates deployed on this Web server be configured to not enforce IP validation for requests from the reverse proxy server that front-ends the Webgate. This is done by configuring the known IP addresses of the reverse proxy server or servers in the IP Validation list. Note that while you can achieve the same effect by turning IP validation off for the Webgate, this is not a recommended approach due to security risks.Ensuring that the Web server only accepts requests from reverse proxies is typically done by adding an ACL statement in the server. This prevents users from bypassing the reverse proxy and directly accessing restricted content.

• Update the virtual hosts that are configured in the Policy Manager so that the Access System intercepts requests that are sent to the reverse proxy.

• Prevent people from circumventing the proxy by entering URLs that point directly to the back-end system.

  You can prevent this problem through the use of Web Server Access Control Lists or firewall filters.

• Since all user requests are processed by the proxy, you must deploy enough proxy servers to enable the system to handle the load.

• Redirect all existing URLs to the host name and port number of the reverse proxy server.

  This often requires configuring the reverse proxy to perform content inspection and rewriting to prevent any absolute HTML links, for instance, to prevent broken link. This is achievable with most reverse proxies, and this is something you can configure independently of the Access System,.

• It is a best practice that URL links exposed to the front-ended applications rely on only relative URLs (../../sub-path/resource) rather than absolute URLs (http://example.com:[port]/path/resource).

  Absolute URLs can break links on the end user's browser when deployed behind a reverse proxy.

22.4.2.2 Configuring Virtual Hosting for Non-Apache Web Servers

Ensure that the Virtual Host box is checked on the OAM Webgate registration page. On most Web servers, other than Apache-based servers, you must set the Preferred Host value to HOST_HTTP_HEADER. This ensures that, when user's browser sends a request, the Webgate sets the value of the Preferred Host to the host value in the request.

For example, suppose a user enters the string example2 in a URL:

http://example2

On the Web server, if one of the Web sites has a host named example2, the request is served by the matching virtual site.

In the Preferred Host field of the expanded OAM Webgate registration page, enter the following:

HOST_HTTP_HEADER.

IIS Virtual Hosting: From the IIS console, you must configure each virtual Web site to contain the following fields:

• Host Header Name

• IP address

• Port

See Also:

• http://www.simpledns.com/kb.aspx?kbid=1149

• http://support.microsoft.com/kb/q190008/

22.4.2.3 Associating a Webgate for Apache with Virtual Hosts, Directories, or Files

Ensure that the Virtual Host box is checked on the 10g Webgate registration page. On Apache-based Web servers (Apache, Apache 2, IBM HTTP Server, Oracle HTTP Server, and so on), the Preferred Host value must be set to SERVER_NAME.

Note:

The SERVER_NAME value is not supported for any host other than an Apache-based server. If you set this value for a non-Apache-based server, users will be unable to access any resources that are protected by Webgate on that Web server. Users will, instead, receive an error that the Webgate configuration is incorrect.

The ServerName directive must be explicitly set with 7777 along with the hostName. This is irrespective of the Listen directive is set correctly. The Server sometimes requires this value explicitly to identify itself, most often it can identify itself automatically.

When using an Apache-based reverse proxy for single sign-on, in the Web server configuration file (httpd.config, for example) file you specify the Web sites to run on the Apache server. The settings can be global across all Web sites or local to a Web site. You can restrict the Access Manager loading references in the httpd.config file to be associated with a specified site, with virtual hosts, specific directories or even files.

To associate the Webgate with specific targets, you move the following directives the the http.conf file:

AuthType Oblix
require valid-user

You can put these directives in a block that tells Apache to use Webgate for every request. You can also move the directives to a block that limits when the Webgate is called. The following is an example of putting the LocationMatch directive after a VirtualHost directive:

  DocumentRoot /usr/local/apache/htdocs/myserver    
  ServerName myserver.example.net    
  AuthType Oblix       
  require valid-user    

After you move the LocationMatch block to the VirtualHost directive, the Webgate will only work for that virtual host. You can add the LocationMatch block to as many virtual hosts as you want. The following examples shows how you could protect one virtual server:

ServerAdmin [e-mail]
DocumentRoot "Z:/Apps/Apache/htdocs/MYsrv"
ServerName apps.example.com
    ProxyRequests On
    SSLEngine on
    SSLCACertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/intermediateca.cer
    SSLCertificateFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_ptcweb32.cer
    SSLCertificateKeyFile Z:/Apps/sslcert_exampleapps_ptcweb32/sslcert_myapps_ptcweb32.key
    ErrorLog logs/proxysite1_log
    CustomLog logs/proxysite1_log common
    ProxyPass /https://apps.example.com/
    ProxyPassReverse /https://apps.example.com/
    ProxyPass /bkcentral https://apps.example.com/bkcentral
    ProxyPassReverse /bkcentral https://apps.example.com/bkcentral
    ProxyPass /NR https://apps.example.com/NR
    ProxyPassReverse /NR https://apps.example.com/NR
    
      AuthType Oblix
      require valid-user
    
#*** BEGIN Oracle Access Manager Webgate Specific **** 
 
LoadModule obWebgateModule Z:/apps/Oracle/WebComponent/access/oblix/apps/webgate/bin/webgate.dll
WebgateInstalldir Z:/apps/Oracle/WebComponent/access
WebgateMode PEER
 
 SetHandler obwebgateerr
 
SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none
 
SSLLog logs/SSL.log
SSLLogLevel info
# You can later change "info" to "warn" if everything is OK

22.4.3 Host Identifier Page

A host identifier is automatically created when an Agent (and application) are registered using either the Oracle Access Management Console or the remote registration tool. In the Application Domain that is registered with the Agent, the host identifier is used automatically.

Administrators can use the console to create and manage host identifiers. Within the Oracle Access Management Console, host identifiers are organized under Shared Components, on the Policy Configuration tab navigation tree. Administrators can manually create a new host identifier definition, modify a definition, delete a definition, or copy an existing definition to use as a template. The name of the copy is based on the original definition name. For example, if you copy a definition named host3, the copy is named copy of host3.

Figure 22-4 illustrates the Create Host Identifier configuration page in the console, where you enter the canonical name for the host, and every other name by which the same host can be addressed by users.

Note:

Each host identifier must be unique. You cannot use the same host name and port in any other host identifier definition.

Figure 22-4 Create Host Identifier Page

Description of "Figure 22-4 Create Host Identifier Page"

Table 22-4 describes the host identifier definitions.

Table 22-4 Host Identifier Definitions

Property	Description
Name	A unique name for this definition. Use only upper- and lower-case alpha characters. No punctuation or special characters are allowed.
Description	The optional description, up to 200 characters, that explains the use of this configuration.
Host Name Variations	Host Name: A list of the various host names or permutations that users might use when accessing the application. See also: "Host Identifier Variations" and "Host Identifier Guidelines". Port: The Web server port used by each host or permutation

22.4.4 Creating a Host Identifier

Users with valid Administrator credentials can create a host identifier definition manually. This is needed if an application and resources were manually added to a host that has no mapped host identifier. When you choose Auto Create Policies when registering an Agent, this is done automatically.

If you copy an existing definition to use as a template, you must modify all unique identifiers in the copy.

See Also:

• "About Host Identifiers"

• "About Virtual Web Hosting"

1. In the Oracle Access Management Console, click Application Security at the top of the window.

2. In the Application Security console, click Host Identifiers in the Access Manager section.

3. Click Create Host Identifier.

4. On the Create Host Identifier page, fill in the:

   1. Name

   2. Description

   3. Host Name Variations: Add (or remove) host name and port variations in the Operations list.

      Add: Click the Add (+) button, then enter a new host name and port combination to identify variables that map to the Host Identifier Name.

      Remove: Click a host name, then click the Delete button to remove it.

5. Repeat step 3c as needed to identify all variations of this host that users can access.

6. Click Apply to submit the new definition (or close the page without applying changes).

7. Close the Confirmation window, and confirm the new definition is listed in the results table.

22.4.5 Searching for a Host Identifier Definition

Users with valid Administrator credentials can search for a specific host identifier.

Note:

During Delete, if the Host Identifier is associated with a resource, you are prompted with an alert. Without any association, the Host Identifier is deleted successfully.

See Also:

"SSO Agent Search Page"

1. In the Oracle Access Management Console, click Application Security at the top of the window.
2. In the Application Security console, click Host Identifiers in the Access Manager section.
3. In the Search Host Identifiers page Name field, enter a name (or a partial name with wild card (*)), or leave the Name field blank to show all Host Identifiers. For example:

   my_h*
   

4. Click the Search button to initiate the search and display results in a table, then:

   • View or Edit: Double-click the name in the Search Results table to display the configuration page, then add or edit as usual.

   • Delete: Click the Delete button in the tool bar to remove the selected item in the results table; confirm removal in the Confirmation window.

   • Detach: Click Detach in the tool bar to expand the Search Results table to a full page (or from the View menu, click Detach).

   • Reorder Columns: From the View menu, select reorder Columns and use the arrows provided to reorder the columns.

22.4.6 Viewing or Editing a Host Identifier Definition

Users with valid Administrator credentials can modify a host identifier definition.

This can include adding, changing, or removing individual host identifiers from the definition. For instance, when adding another proxy Web server with a different host name, you might need to modify an existing host identifier definition to add the new host name variation.

Prerequisite: Inventory Application Domains that refer to the host identifier and

Note:

After viewing settings, you can either close the page or modify settings as needed.

See Also:

"Host Identifier Page"

1. Locate the desired host identifier and view it as described in "Searching for a Host Identifier Definition".

2. On the Host Identifier page, modify information as needed (Table 22-4):

   1. Name

   2. Description

   3. Host Name Variations: In the table provided:

      Add (+) Host Name Variations: Click the Add (+) button, then enter a new host name and port combination to identify variables that map to the Host Identifier Name.

      Delete (X) Host Name Variations: Click a host name, then click the Delete button to remove it.

3. Repeat step 3c as needed to add or remove variations.

4. Click Apply to submit the changes (or close the page without applying changes).

5. Dismiss the Confirmation window, and close the page when you finish.

22.4.7 Deleting a Host Identifier Definition

Users with valid Administrator credentials can delete an entire host identifier definition. A validation error occurs if you attempt to delete the host identifier that is being used in a resource.

If the Host Identifier is associated with a resource, you are alerted. Without any association, the Host Identifier is deleted.

Prerequisites

Each resource in an Application Domain is associated with a specific host identifier. If you intend to delete a host identifier you must first modify any resource definitions in an Application Domain that uses this host identifier.

See Also:

"Viewing or Editing a Host Identifier Definition" if you want to remove a single host identifier from an existing definition.

1. Locate and modify related resource definitions in any application domains that uses this host identifier. See "Searching for a Resource Definition".
2. Locate the desired host identifier as described in "Searching for a Host Identifier Definition".
3. View: Double-click the name in the results table to display the configuration page, and confirm this can be removed.
4. Delete: Click the Delete button in the tool bar to remove the selected item in the results table; confirm removal in the Confirmation window.