OAM 11g Policy Model Part 2: Application Domains and Host Identifiers

This is the 2^nd post in my series going over the OAM 11g policy model and another post in the broader OAM 11g Academy series.  To view the first post on the OAM 11g policy model, as well as the index to the entire OAM 11g Academy series, click here: http://fusionsecurity.blogspot.com/2011/02/oracle-access-manager-11g-academy.html.

In this post I will go over two different but higher level constructs of the OAM 11g policy model, the Application Domain and Host Identifier.

Application Domains

Application Domains are high level “container” objects for lower level policy objects. They mostly represent an organizational layer in the OAM 11g policy model. Application domains contain 3 types of objects: resources, authentication policies, and authorization policies. From an abstract point of view application domains are supposed to represent all the resources and policies associated with a given application or group of applications.

Now you might be saying to yourself that since resources can only be a part of one authentication policy and one authorization policy at a time, that one could always just go with one huge policy domain containing all resources, authentication and authorization policies in existence. Well, as things stand today you’d be right.

However, there is a good chance that future OAM 11g enhancements will make more concrete use of Application Domains. I also think that it is probably a good idea to organize your OAM policies and resources by application or groups of applications. So, I encourage people to go with the flow and use application domains as they were intended to be used.

The question then becomes where does one draw the line in terms of what do we mean by application or application group? I think this is largely subjective, but that if you are creating policies for J2EE applications that it is probably a good starting point to create one application domain for every enterprise application (EAR).

Host Identifiers Overview

Host Identifiers are very similar to what they were in the OAM 10g model. They serve as a binding between hostnames or groups of hostnames and URIs. I see many people confused by the host identifier concept and so I will cover this in a lot of detail.

If you look at an HTTP request, it is composed of 4 components the protocol (HTTP), the hostname, the URI, and the query string: http://hostname/URI?queryString. For example http://www.acme.com/foo/bar.jsp?x=y

OAM policies ignore the protocol and query string components in the request and consider the resource to be the hostname + URI. Host Identifiers represent hostnames or groups of hostnames in OAM policies. The reason why OAM supports the notion of host identifier instead of just having policy authors use full URLs is because a single web resource may be accessible through any number of hostnames.

So, host identifiers are great but there is a lot of confusion out there over how to configure and use them in OAM. So, let me lay it out for you. Stay with me because there is actually a lot to cover here.

There are 3 places that host identifiers come into play in configuring OAM 11g:

1. The configuration of host identifiers themselves.
2. The “Host Identifier” field that you see as you go through agent registration. This becomes the “preferred host” field in the agent configuration screen. It is a little confusing but what you enter in here is not the name of the host identifier itself but the string you want the OAM server to use in resolving which host identifier to attach to the request. More on this in a bit.
3. When you create a resource you specify a host identifier that along with the resource URL (an expression matched to the URI of the request) specifies a resource in OAM. Again, the host identifier represents one or more hostnames that a resource can be requested through.

Host Identifiers in OAM Process Flow

The request process flow of OAM 11g that is relevant to host identifiers is as follows:

1) A request comes into the web server. If the preferred host (host identifier) has been specified in the agent config for the agent intercepting the request then OAM will include the value of preferred host in the “host” field of the “is protected” call made to the OAM server to determine whether or not the request is protected and if so by what authentication scheme.

For virtual hosting support you can also specific the string SERVER_NAME on Apache based servers and HOST_HTTP_HEADER on other web servers.

On Apache based servers this will result in the agent sending down whatever Apache sets as the SERVER_NAME “environment variable”. This is generally governed by the ServerName directive of the httpd.conf or ssl.conf. For more information about ServerName and virtual hosting in Apache, see the Apache documentation on the subject.

On other servers, I believe that the HOST_HTTP_HEADER setting will send down the value of the HTTP header: HOST. However, I have not played with this yet so don’t be surprised if it actually works a little differently.

2) When the request arrives at the OAM server, OAM does a search of the configured operations (hostname + port) in each host identifier object looking for a match with what was sent down in the “host” field of the “is protected” call in step 1 above. If it finds a match it will use the host identifier the match was found in as the host identifier portion of the request as processing proceeds. If it does not find a match then it will reject the request sending back a “not protected” response to the agent, which in 11g will always cause the request to be blocked.

The important thing to understand here is that even though the documentation talks a lot about listing all the combinations of hosts and ports as you configure the host identifier and the operations are configured as hostname + port pairs, the “host” being sent down with the “is protected” call is just a string and the port being sent down is just a string.

In the case of a statically configured preferred host, this string is completely static. You can enter a preferred host of ‘purple_elephant:1234’ and in the operations of your host identifier enter host: purple_elephant port: 1234 and everything will work fine. It is also worth noting that you’ll get a match if you don’t enter a port in the preferred host while at the same time leaving the port blank in the operations hostname-port pair.

In the case of preferred host = SERVER_NAME then this string comes from the web server but is still somewhat arbitrary and doesn’t necessarily have to be the value of the HTTP HOST header.

3)  Finally, OAM goes through the process of trying to match the request to a resource in the OAM policy.  So what it does here is to go through the resource objects that have the host identifier that was identified for the request in step 2 above and tries to match the URI of the request against the resource URL in the resource object.  I’ll talk more about this matching process in a future post.

Static vs. Dynamic Preferred Hosts

The decision on whether to use a static preferred host in your agent configuration vs. a dynamic one where you use the value SERVER_NAME (for Apache) or HOST_HTTP_HEADER (for other web servers) confuses some people but is actually fairly straight forward.

For agent X, if the resource identified by any given URI /xyz is always the same, regardless of the hostname (virtual host) that the request came in on, then you can use a static preferred host.

However, if any URI designates one resource when the request comes over one host but a different resource when the request comes over a different host, then you should use a dynamic preferred host and create separate host identifiers for each virtual host being protected by that agent.

For example, let’s say agent X is running in a web server that is hosting hr.acme.com and sales.acme.com which are the hostnames for completely separate applications that both contain the URI /index.html. Then you should use a preferred host of SERVER_NAME (or HOST_HTTP_HEADER) for agent X and create host identifiers hr and sales with their respective hostnames hr.acme.com and sales.acme.com configured as operations of the respective host identifiers.

Step-By-Step Configuration of Host Identifiers

Here I will show the configuration of an agent, host identifier, and resource for both the static and dynamic models of host identification.

The following is a host identifier object configured that I used to test the static model of host identification where a static preferred host is configured in the web agent configuration. Notice how I use colored elephants as the operations without specifying a port. I did this to illustrate that we are really just working with strings here, that the agent will send down whatever is configured in the preferred host directive and that as long as this string appears in the operations of the host identifier that things will work fine.

following is the corresponding agent configuration object.  The relevant directive is preferred host.

The following is the agent object for the dynamic model of host identification.  The key here is to set the Preferred Host directive to the special value of SERVER_NAME (HOST_HTTP_HEADER on non-Apache based servers).

Then here we have the corresponding host identifier object for the dynamic model.  Note how I still have left off the port for some of the hostname/port pairs.  This is because, if you do not include a port in the ServerName directive in your Apache configuration (httpd.conf) then the agent will not send down a port.  In my example I left the port off for my HTTP virtual hosts and included the port for my HTTPS virtual hosts.

Finally, here is an image of configuring a new resource object in an OAM policy and selecting the appropriate host identifier object that we just spent all this time talking about.