I have included two images of flow charts in this blog entry that show how a request for a resource is processed: one image is web-agent specific and one is J2EE-agent specific.

These charts show the possible scenarios that can take place when an end user makes a request for a resource. Therefore, the end user points a browser to a URL. That URL is a resource, such as a JPEG image, HTML page, JSP page, etc. When an agent is configured to protect that resource ("protect" is not always the correct word, but the agent has a role to watch the resource anyway), it intervenes to varying degrees and checks the request. The situation might be that all requests are granted for that particular resource. Maybe then the request is logged and maybe it isn't logged. Hopefully, the flow charts reflect the key details.

Coming up with a flow chart that provides just the right level of detail is a tricky proposition: too much detail and the image is too complex; not enough detail and the image doesn't provide much useful info. Anyway, after getting much input from developers, this is what I came up with.

The flow chart that  follows illustrates how a request for a resource is handled by a web agent. Therefore, the web agent is protecting resources on a web server or web proxy server. The flow chart shows the processes the web agent goes through to protect such resources.

 How a Resource Request is Processed by a Web Agent

The flow chart that  follows illustrates how a request for a resource is handled by a J2EE agent. You can see that the J2EE security that is available in application servers (though J2EE agents often protect resources on portal severs, too) adds a layer of complexity to the chart. The J2EE agent flow chart also shows how the filter mode setting affects the processing of a request.

 How a Resource Request is Processed by a J2EE Agent

11/01/08: The flow chart in the link that follows was updated today. The "Yes" lines coming out of the top right side were not aligned properly. The problem has now been fixed. However, the print was too small and difficult to read. Therefore the image has been split into two (see below). It should be easier to read.

To see the two images combined as one, see the following: Single Image. 

------------------------------------------

11/06/08: The following two flow charts were just updated today. The original chart has been split into two to allow the text to be larger. Hopefully, it's easier to read this way.

For the most up-to-date information about the use of wildcards for OpenSSO policy definitions, see the following page on the OpenSSO wiki:

I've written a couple of blog entries on wildcards lately:

• Wildcards for OpenSSO
• OpenSSO: Wildcards and Handling Resources with Query Strings

Christopher Nebergall left a comment on the "Wildcards for OpenSSO" entry saying the following:

"Would it make more sense for you to put doc entries like this blog post into one of the Sun wiki's instead of your blog? Then others like myself could help provide content and help keep it up to date."

I thought that was such a grand idea that I created the Wildcard Matching in OpenSSO wiki page.

Okay, so now, that should be the go-to place for wildcard information related to OpenSSO. So information on wildcards and their relationship to query strings and the like will be most up-to-date on that wiki page. I would venture to say that that page will end up being more current and comprehensive than the official documentation on the topic.

If you want to learn a lot about OpenSSO as quickly and easily as possible, look no further than the free lab AM-3508-D. Training course developer, David Goldsmith, has really outdone himself here. He has put together a lab that can really change how training is done in the future for OpenSSO.

This type of training course has tremendous potential. This should really be able to serve the OpenSSO community. Lab AM-3508-D is described in several places, including the following:

• David's own blog entry on this lab
• Pat Patterson nicely summarizes the lab
• An explanation of this lab in Japanese by Kimimasa Sato
  
• An explanation of this lab from Sidharth Mishra
• An explanation of this lab from Daniel Raskin
  

Anyway, there was a lot of buzz on this lab when it first came out and I've continued to hear great buzz since. Like I said, the potential here is great. I finally got around to starting the lab. It looks great. You have the whole lab in a VMware virtual machine, all self contained and beautiful. It's just great! (Have I used the word "great" enough? Really, it's great!). You install and configure the OpenSSO related products. Your not watching someone do it. Your not reading about how to do it. You just do it. To borrow a phrase, "It just works!" You can jump forward or roll back anywhere along the way. This is really, really what training aspires to be. This kind of learning can really reach the community easily, too. Often classroom training is just not feasible.

To get the lab, I used the OpensSSO publication team's Windows laptop to download the free Sun Download Manager 2.0 for downloading large Sun downloads (downloading it and installing it took all of 3 minutes). Then I downloaded the free labs (thhis took a while because they're in a virtual machine which is a huge download). Then I downloaded the free VMware Player (downloading it and installing it took all of 7 minutes).

To be fair, I must explain that I first tried to downlaod VMware Server. You can create your own virtual machines with VMware server, but not VMware Player. However, I ran into problems with VMware Server. You need to provide the fully qualified domain name, so I issued ipconfig from a command window. It seemed like I had it figured out. I'm wondering if there was a permissions problem. I had a browser interface that was letting me control the VMware Server interface, I had the  lab 3508-D virtual machine all loaded. Then, bam! I got an error that wouldn't let me continue. I uninstalled VMware Server, downloaded and installed VMware Player and all is goodness.

The lab is all on Solaris, so you'll do everything in a Solaris environment. You get to learn some pretty trick Solaris things along the way, such as the concepts of "zones" and "ZFS." You can stop and come back later to the same spot, or skip forward or fall back amongst labs. I'm just starting, so it's too early to say too much.

I thought that just getting the lab started might be an ordeal, but it wasn't. It's especially easy if one uses VMware Player, since it's so lightweight and simple.

Bottom Line: If you want to learn about how to use OpenSSO and Policy Agent 3.0 and a lot, lot more, do this free lab. Did I mention that it's free?

NOTE ADDED 10/11/08: For the most up-to-date info on wildcards see the following link:

In my previous blog entry, Wildcards for OpenSSO, I provided the write up I plan to include for OpenSSO documentation. I got some feedback. One piece of feedback came in the form of a blog comment at the end of the entry. I responded to that comment with my own comment. The other piece of feedback had to do with query strings in URLs, and that comment came in the form of an email message through the following mailing list: users@opensso.dev.java.net. Obviously, I'm subscribed to that mailing list.

In fact, when I submit a new blog entry, I often send an email message to that mailing list. This is a great community approach that I picked up from other Sun bloggers. When it comes to feedback, I feel that comments on the blog are actually better because people who haven't  subscribed to the mailing list still can see the comment. All the same, the mailing list is great. I feel that the OpenSSO community is really starting to gel. It's easier than ever to interact with the community now. Anyway, the following link is to various OpenSSO related mailing lists:

https://opensso.dev.java.net/servlets/ProjectMailingListList

The "users" mailing list has a lot of activity. To sign up to one of the mailing lists, you first need to register to the OpenSSO project. You can also do that from the link listed above.

All right then, for the the comment I received about query strings, I wrote up a couple of short paragraphs that I'll add to my wildcard write up. I've added those paragraphs below. Leave a comment if you have anything you can add or suggest for these two extra paragraphs.

Handling Resources That Contain Query Strings:

Some resources use a query string, which is the part of a URL that contains data to be passed to web applications. The following is a feasible example of a URL that contains a query string: http://AgentHost/path/app?query-string. The question mark (?) is the separator. It is not part of the query string. Many scenarios exist in which query strings might be used. They can be used for personalization of the user's session. Sometimes an application might add some locale information for a page request. The following example demonstrates the use of such locale information:
http://AgentHost.com:8080/sampleapp/main.jsp?language=en&country=US.

Neither the multi-level wildcard (*) nor the one-level wildcard (-*-) match the question mark. Therefore, to define a policy resource that can handle the question mark, use the multi-level wildcard on both sides of a question mark, as follows: *?* (asterisk-question mark-asterisk).

NOTE ADDED 10/11/08: For the most up-to-date info on wildcards see the following link:

http://wikis.sun.com/display/OpenSSO/openssowildcards

Earlier this year, Michael Teger blogged about wildcard use for our products as follows:

http://blogs.sun.com/docteger/entry/wildcard_matches_in_policy_agents

http://blogs.sun.com/docteger/entry/one_more_wildcard

I used this information to put together a write up for the OpenSSO Enterprise 8.0 and Policy Agent 3.0 documentation. I talked to a few developers to get some more info and to have them double check everything. So this should completely explain how you can use wildcards for policy-related situations when configuring OpenSSO or Policy Agent.

If anything looks unclear to you in this write up, please leave a comment.

 Below is the write up about wildcard use in OpenSSO and Policy Agent.

Wildcard Matching in OpenSSO

The OpenSSO Enterprise policy service supports policy definitions that use either of the two following wildcards:

• The Multi--Level Wildcard: *

• The One-Level Wildcard: -*-

These wildcards can be used in policy related situations. For example, when using the OpenSSO Enterprise Console or the ssoadm utility to create policies or when configuring the Policy Agent property to set the not-enforced list.

Caution - When issuing the ssoadm command, if you include values that contain wildcards (* or -*-), then the name/value pair should be enclosed in double quotes to avoid substitution by the shell.

For creating a policy, the following are feasible examples of the wildcards in use: http://agentHost:8090/agentsample/* and http://agentHost:8090/agentsample/example-*-/example.html.

For the not-enforced list, the following are feasible examples of the wildcards in use:
Web Agents:
http://agentHost:8090/agentsample.com/*.gif and http://agentHost:8090/agentsample/-*-/images

 J2EE Agents:
/agentsample.com/*.gif and /agentsample.com/-*-/images

Note - A policy resource can have either the multi-level wildcard (*) or the one-level wildcard (-*-), but not both. Using both types of wildcards in the same policy resource is not supported.

The Multi-Level Wildcard: *

The following list summarizes the behavior of the multi-level wildcard (the asterisk, *):

• Matches zero or more occurrences of any character except for the question mark (?).

• Spans across multiple levels in a URL

• Cannot be escaped. Therefore, the backslash character (\) or other characters cannot be used to escape the asterisk, as such \*.

The following examples show the multi-level wildcard character when used with the forward slash (/) as the delimiter character:

• The asterisk (*) matches zero or more characters, except the question mark, in the resource name, including the forward slash (/). For example, ...B-example/* matches ...B-example/b/c/d, but doesn't match ...B-example/?

• Multiple consecutive forward slash characters (/) do not match with a single forward slash character (/). For example, ...B-example/*/A-example doesn't match ...B-example/A-example.

• Any number of trailing forward slash characters (/) are not recognized as part of the resource name. For example, ...B-example/ or ...B-example// are treated the same as ...B-example.

Table B-1 Examples of the Asterisk (*) as the Multi-Level Wildcard

The One-Level Wildcard: -*-

The one-level wildcard (-*-) matches only the defined level starting at the location of the one-level wildcard to the next delimiter boundary. The “defined level” refers to the area between delimiter boundaries. Many of the rules that apply to the multi—level wildcard also apply to the one-level wildcard.

The following list summarizes the behavior of hyphen-asterisk-hyphen (-*-) as a wildcard:

• Matches zero or more occurrences of any character except for the forward slash and the question mark (?).

• Does not span across multiple levels in a URL

• Cannot be escaped. Therefore, the backslash character (\) or other characters cannot be used to escape the hyphen-asterisk-hyphen, as such \-*-.

The following examples show the one-level wildcard when used with the forward slash (/) as the delimiter character:

• The one-level wildcard (-*-) matches zero or more characters (except for the forward slash and the question mark) in the resource name. For example, ...B-example/-*- doesn't match ...B-example/b/c/ or ...B-example/b?

• Multiple consecutive forward slash characters (/) do not match with a single forward slash character (/). For example, ...B-example/-*-/A-example doesn't match ...B-example/A-example.

• Any number of trailing forward slash characters (/) are not recognized as part of the resource name. For example, ...B-example/ or ...B-example// are treated the same as ...B-example.

Table B-2 Examples of the One—Level Wildcard (-*-)