... h1. Sample application for opensso policy agents
The J2EE Agent download contains a sample application that you can try out and learn more about using the J2EE agents and the Access Manager to secure a web application.
See the [sample application troubleshooting page | http://wikis.sun.com/display/OpenSSO/GlassFishAgentSample] if you have problems.
0) download and install the am/fam/opensso.war server and a policy agent.
1) Find the sample application.
When you downloaded the agent, for example appserver_v9_agent.zip, and unzipped it, you will can look inside j2ee_agents\appserver_v9_agent\sampleapp\ directory of your agent unzip.
2) Find and use the readme
Where are instructions to use the sample application?
The official [Agent Guide | http://docs.sun.com/app/docs/doc/820-2539]documents how to configure an application to be protected by the J2EE agents so it is a useful general document. The sample application also contains a *readme* file which outlines in some detail many of the steps needed to configure the agent for the smaple application. This readme file is where you need to start. It explains all the steps to configure and deploy the sample application and some steps to configure a security policy on the fam/opensso server. SEE STEP 3 since it can be used with readme.
3) Use this with the readme
This next step contains some EXTRA INFORMATION to set up the policy.
It has some screen shots and details about the stpes to set up the policy as described in the readme. The readme instructions are brief, so the next step expands on them.
See [details for creating the sample application policies | samplepolicy] on the am/fam/opensso server, as decribed in agent sampleapp readme.
4) Additional Features to try with the sample application
Here are some extra things you can try with the same app so that you can learn about some new features. This assumes you have the agent and opensso server installed and the agentsample app already successfully deployed.
* Logout: Try the logout feature. Just go to the opensso console UI and click on that agent's configuration, in the Application tab under the LogoutProcessing section go to the property label Application Logout URI for the property named com.sun.identity.agents.config.logout.uri. Now in the Map Key field enter agentsample and in the Corresponding Map Value field enter /agentsample/logout and click add. If you have notifications enabled then in a moment your agent will receive this new configuration change so now you can use it. Now go to the agentsample in the browser and access a protected page resource and then log in to the application as one of the user subjects you created for the sample, then go to this url http: //host:port/agentsample/logout for your own host and port values for example http: //my.test.domain.com:6948/agentsample/logout
Note, the logout page does not actually have to exist, if the agent receives a request for a resource agentsample/logout it will invoke the logout feature. This will log the user out from the application. You can verify that the user is logged out by trying to access a protected page resource and seeing that you are again asked to login, indicating ou have been logged out. An alternative way to verfiy logout is to go to the opensso UI console main page and click the Sessions tab which will list all active sessions and you will see that the user is no longer listed since you logged out of the aplication.
* Attribute Fetch Features:
These features allow you to make some of the data in opensso server available to your applications for customizing your applications. For example, your applications may want information about users profiles or sessions or policy to customize applications or do some fine grained programatic security. See the Attributes [http://wikis.sun.com/display/OpenSSOFetching properties page for more details | fetchingattributedetails]. Lets try some of this out. We will make some of the user profile information available for som eof the subjects you created when configuring opensso for the agent sample application. You create subject users such as "chris" and when you created them they are persisted in the opensso user data store with a bunch of user supplied attributes and some default attributes like first name, last name, and membership information etc. We would like to make this information available to the sample application and using the attribute fetching feature we can enable the agent to automatically inject the desired user profile attributes into the headers or requests or as cookies so that the application can then access them through standard programming mechanisms of J2EE.
The agent sample application already includes a showHttpheaders.jsp page which lists out all the attributes that are available in headers or requests or as cookies, and you can see in that page that it already contains some information. |
Now, lets try to use the fetching features to add some additional user profile information to show in the showHttpheaders.jsp page. Go to the opensso console UI page, navigate to the agent configuration for the agent you created for the deployed sample application. After choosing that agent, in its configuration page, click on the Application tab, now click on the Profile Attributes Processing section, and in the label Profile Attribute Fetch Mode: for the property named com.sun.identity.agents.config.profile.attribute.fetch.mode choose either HTTP_COOKIE, or HTTP_HEADER or REQUEST_ATTRIBUTE as the mode. This will determine whether the user profile attributes we will next specify will be injected into headers or request attributes or as cookies. Now lets specify some user profile attributes. You can log into opensso console as one of the subjects you created, such as "chris" and see more attributes for the subject on the page and also can chage som eof the values. If interested you can find out more about the avilable attributes in a user profile by checking the opensso documentation. Some of the attributes that are stored for the subjects we created are things like the users first name and last name and email and these are available with under some attribute names, for example last name is available under the attribute "sn" and first name is available under the name "fn". So lets add some of these attributes into the fetching feature. Again in the Application tab page, in the Profile Attributes Processing section, and under the label Profile Attribute Fetch Mode: find the lable Profile Attribute Mapping: for the property named com.sun.identity.agents.config.profile.attribute.mapping and in the Map Key field enter +sn+ and in the Corresponding Map Value field enter LastName. Note the value you specify in the Corresponding Map Value field is the name under which the value will be avalable in the sample application and will show up in the sample application showHttpheaders.jsp page table. Then click Add to add the sn=LastName into the mappings. Now do the same thing for a couple more attributes, enter the key cn and value CUSTOM-Common-Name and click add, now enter the key MemberOf and value agentmember and click add, and now we will add an attribute which is not available to demonstate that it will be passed but will have no value injected into it, so now now enter the key ou and value organiz and click add.
Now BE SURE to click SAVE to save these changes. |