OAM 11g PS1 (126.96.36.199) introduced two important enhancements related to resource definitions in the policy model:
- The ability to optionally include query strings as part of resource definitions.
- The designation of a protection level for a resource and the completely new concept of excluded resources that go with it.
In 188.8.131.52, resources could not include query strings and OAM essentially ignored query strings in its policy evaluation. In 184.108.40.206, there is a specific field for query strings in the resource definition screen of the OAM console that you can optionally make use of. We’ll come back to this in a future post.
For now I’ll point you at the documentation but also point out that you don’t have to define query strings if you don’t want to. Incoming request for resources that include query strings will still resolve to resources that have blank query string parameters. For example, if you define a resource /foo/bar.jsp and leave the query string field blank, it will still match requests for /foo/bar.jsp?x=y and the like.
With that out of the way, I’d like to talk about the 2nd important enhancement to resource definitions in OAM 11g and that is the notion of protection level and in particular the designation of excluded resources.
When you define a resource in OAM 11g PS1, you specify a protection level from 1 of 3 choices: protected, unprotected, and excluded.
Protected resources must be included in an authentication policy that uses an authentication scheme with a protection level greater than 0. Protected resources can be associated with any authorization policy.
Unprotected resources must be included in an authentication policy that uses an authentication scheme with a protection level of 0. Most often this will be the anonymous authentication scheme. Unprotected resources can be associated with any authorization policy. Indeed, OAM will block access to unprotected resources that are not included in an authorization policy.
However, it is worth noting that it probably doesn’t make sense to put an unprotected resource into an authorization policy with constraints. If you plan on applying constraints to requests to a resource, then you should make that resource protected.
Session validation is still performed on requests to unprotected resource. However, if a user session times out or is otherwise invalidated and a user tries to access an unprotected resource, they will be let through but their name will not be propagated in the OAM_REMOTE_USER header, rather OAM_REMOTE_USE will be set to anonymous.
Basically, unprotected resources are the pre-PS1 equivalent of associating a resource with the anonymous authentication scheme.
Excluded resources are entirely new to PS1 (220.127.116.11). When a request comes in and matches up with a resource that has been designated as excluded, then the webgate/agent just lets the request through.
No calls to the OAM server are made, no session validation is performed, and the OAM_REMOTE_USER header is not added to the request. Also of note, if you have configured your webgates/agents to issue certain cache control headers back to the browser, they will not be issued in the case of excluded resources.
As you can probably see, OAM’s handling of excluded resources is very fast because, well, it isn’t doing much for them.
Unprotected vs. Excluded
At this point (if you are like me) you are probably wondering about when resources should be designated as excluded and when they should be designated as unprotected. On some levels these are very similar designations, although there are some important differences.
For performance reasons, I think it is a good idea to designate as many of your resources as possible as excluded. At the same time you want to make sure that your applications are still secure and functional. So, I’ve come up with the following guidelines:
1) If a resource is private, which is to say only authenticated users should have access to it, then if should be designated as protected.
2) If the resource is public, which is to say that authenticated and unauthenticated users should have access to it but you want to be able to know the names of authenticated users and/or set responses to create headers containing certain information about authenticated users, then the resource should be designated as unprotected.
3) If you want to audit requests to a resource using OAM then a resource should be designated as protected or unprotected. Note that you can still audit using web server logs for excluded resources.
4) If you want session validation to be performed in advance of populating the OAM_REMOTE_USER header, then a resource should be designated as protected or unprotected.
5) A corollary to items 2 and 4 above is that if you want the WLS SSO Synchronization filter to be active and “protect” a resource should be designated as protected or unprotected. This is an important note for those using OAM to protect Oracle WebCenter or ADF based applications.
6) If none of the above are true and you have a resource that is public, that doesn’t need to know anything about the user, where you don’t care about using OAM to audit access to the resource, and you don’t care about the WLS SSO Synchronization Filter for the resource, then (finally) you can make the resource excluded.
Short Cut Guideline
A short cut to the above guidelines that many will find useful is to designate as excluded public static resources such as images, PDF, and static html.
If such resources are grouped in directories then you can exclude them by defining policies like:
If such resources are more scattered, then you should be a little more careful and define resources individually or by file/content type like:
The notion of protection level for resources is an important addition to OAM 11g. The designation of excluded resources is likewise very important and will prove very useful for maximizing performance of your OAM enabled applications. You can read more about protection levels, excluded resources, and query strings in resources (which we’ll blog more about later) in the 18.104.22.168 documentation: http://download.oracle.com/docs/cd/E21764_01/doc.1111/e15478/app_domn.htm#BABJDGBB