getstarted

h1. Getting Started with OpenSSO and Policy Agents
This is a rough draft of an unofficial tutorial to get you started with opensso and the policy agents.

This will focus on using opensso 8.0 and Policy Agents 3.0. Some of the instructions will use specific examples from using GlassFish as the application server. If you are using another server, this could server as a rougher guide to get started.

If you want the longer versions and official docs, please see [the official docs site | http://docs.sun.com/app/docs/prod/fed.accmgr80~1767.1]

h3. 0-a. Create some Fully Qualified Domain Names (FQDN) to use
The AM/FAM/opensso server and policy agents requires FQDN for the host name of the machines where you will do your installations. You can *NOT* use a host name like "localhost" and can *NOT* use numeric IP addresses like "129.777.777.123" as host names either, else it will *cause problems* in installation, configuration and usage. You have to use FQDNs, for example like my.test.domain.com in your URLs such as http ://my.test.domain.com:6948/opensso for url values you use in agent installers etc.

PLEASE, set up some alias for the host names of the machines where you plan to do your installation. It is easy to do.
See [this tip on how to set up some FQDNs to use | http://wikis.sun.com/display/OpenSSO/J2EEAgentTrouble#J2EEAgentTrouble-fqdn]

So now create the two domain instances. GlassFish comes with one pre-made domain called *domain1* already and it takes up port 8080 for its urls. So for instance you could access it at http://localhost:8080 which of course we DO NOT want to do, because we want to always use FQDNs so would access it at http://my.test.domain.name:8080 Please rememer to always use a hostname like my.test.domain.name and not localhost, else things wont work.
Since GF(GlassFish) already has a domain called domain1 lets use it. This is where I suggest you deploy the opensso.war in a later step, step 2.

But we need a second domain, where we will install the agent and deploy our sample apps. Its fairly easy to create domains on GF. This is also handy, because sometimes if an agent installation goes bad an dit is easy to just create another domain and reinstall the agent.
The command for GF to do this is somthing like
asadmin create-domain --portbase 6868 domain2
and then you maybe enter the name *admin* for the adminuser and then the password like adminadmin a couple times.
The exact command sytax may vary depending on exact GF version but if you need to add another flag or option the error message usually suggests the expected syntax.
This command will create the domain and assign it some ports, in particular it will asign an http port and this info will be printed out when the command is run. Usually this command if given as above will assign http to the port 6948 so your url for applications on this domain would be for example http://my.test.domain.com:6948

h3. 1. Download the OpenSSO server
Opensso can run on many application servers, but for this tutorial we will show the steps on glassfish.
If you are not picky about what server you use, I recommend using [GlassFish | https://glassfish.dev.java.net/] as the installation works very well on this server, and the instructions I will post will follow an installation I did on GlassFish.
You can [download opensso very stable and official versions | http://www.sun.com/software/products/opensso_enterprise/get.jsp]
If you really want the latest and greatest builds,
you can download opensso from [the opensso project site | https://opensso.dev.java.net/public/use/index.html]

h3. 2. Install opensso.war
See this article for details on this step.
[Deploying OpenSSO on GlassFish Application Server | http://developers.sun.com/identity/reference/techart/opensso-glassfish.html]
This article gives a brief explanatin of installing and configuring opensso.war.

If you want lots of detail and documents for OpenSSO server, see the [official set of docs site | http://docs.sun.com/app/docs/prod/fed.accmgr80~1767.1]

h3. 3. Choose and Install an agent.
We are using OpenSSO Policy Agents 3.0 here.
h5. 3-a. Choose an agent to download
Choose an agent to download for the web container you would like to run some sample applications on. There are agents for many Java EE servers like GlassFish, Tomcat, weblogic, websphere etc, , and we also have non-Java Agents such as for Apache httpd and MS IIS etc.
In this tutorial we will focus on the GlassFish agent, though the steps are roughly the same for any of the apservers.
[Check out this download page and download the J2EE Agent 3.0 for Glassfish/Sun Application Server. | https://opensso.dev.java.net/public/use/agents.html]

h5. 3-a Unzip the agent download and explore
After you have downloaded an agent, then unzip it under some directory like C:\myagents\ and then explore the unzipped agent download a bit.

h5. 3-b. Install agents
In this setp you will install the agent. Remember we will install the agent on domain2 (or some separate domain from where the opensso.war is deployed). Here are some important tips when you install the agent:

The official docs of interest if you want longer explanations would be
*
[Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents | http://docs.sun.com/app/docs/doc/820-4803/gannk?a=browse] which describes some general features of the opensso agents for Java EE.
* [Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Sun Java System Application Server 8.1/8.2/9.0/9.1 and GlassFish | http://docs.sun.com/app/docs/doc/820-4578/6ng1jrj42?a=browse]
This describes the installation using the "agentadmin --install" command and then the post installation steps.

Or the shortcut version...here are some [instructions to install OpenSSO Glassfish Agent 3.0 nightly build | b5agentinstallinstruction]

NEED TO ADD A VERY RECENT VERSION OF SHORTCUT HERE since build 6 has slightly different questions, though very similar.


h3. 4. Install the mini-application
This is a super simple Java web application that contians two JSP pages, which will demonstrate some basic features of opensso. Also, by setting it up and using it, it is a good way to test that your set up and config is solid, so you can have confidence trying more advanced stuff. or if problems, then can resolve them before going forward.
Please read this article and download and try its minin-sample app. The article details the steps and shows screen shots and has some explanations fo what is going on.
[Go try it now and come back here afterward |http://developers.sun.com/identity/reference/techart/policyagents.html]
Things you will learn: Simple example of Login, authentication, protecting pages of a web application. Creating users on opensso, general familiarity of the opensso console UI, etc.

h3. 5 Try article two
[Go try it now and come back here afterward |http://developers.sun.com/identity/reference/techart/policyagents2.html]
This uses the same mimi-application as part 1 of this article series, so is an easy step after th efirst article. It shows how to protect certain pages and also how to make some pages like an home page public accessible to any users. Plus it demonstrates how easy it is to do single signon with opensso. See how you can sign into one app and automatically be able to access the other app. It has screenshots and brief explanations.

h3. 6. Sample application of policy agents
The policy agents come with a sample web application with a readme file that explains how to deploy the sample app and then to configure it to be secure. It is included in the download zip of your agent.
{noformat}DOING THIS SAMPLE APPLICATION WILL TEACH YOU THE BASICS
OF USING OPENSSO SERVER AND POLICY AGENTS WITH WEB APPLICATIONS. {noformat}
It shows many features such as using Java EE security mechanisms with opensso. This really is the a great way to get started, and once you finish it is easy to then make your own sample apps and then use opensso to try and more things.
Check out the [agent sample page | agentsample] for more detail.

h3. 7. Try some other features
Want to learn some more? If you already got the sample apps above working with simple SSO, now maybe try a few more things...
* if you want to allow anonymous access so any user can access certain pages then you can try out some other agent configuration to set certain URLs as *not enforced* by the agent, so then no sign on is required to access them. See the J2EE agent property com.sun.identity.agents.config.notenforced.uri list and add some of the applications URLs and try it out
* if you want to have a finer grained security policy where certain users can access certain resources, then set up a policy on the opensso server. the sample application shows how to do this. Try to set up a simple policy for the simpleapp.war and restrict certain users to certain pages
* if you want to have a common access denied page showing when a user is not allowed access to some page (instead of just browser default page for 403 error), then set the property for com.sun.identity.agents.config.access.denied.uri = some page, and maybe add a page into the simpleapp.war.
* if you have also set up the J2EE agent sample application, then it can also participate in SSO with the other 2 web apps. This way you can see an example of a web app using J2EE declarative security (web.xml security elements) and a simple web application(no security specifies in web.xml) can work together. Make sure you have the J2EE agent property com.sun.identity.agents.config.filter.mode = ALL so that the sample app can use its J2EE security to login to J2EE container security as well.
* Try Cross Domain Single SignOn CDSSO, the agents can also handle this. see the documentation on enabling CDSSO in the agents.
* Try some SAML or Federation

h3. Other links
* Avoid redirect problem. There is an intermittent issue that causes browser redirect issues with am server and agents occssionally. See the [solution section of this faq | http://wikis.sun.com/display/OpenSSO/J2EEAgentTrouble#J2EEAgentTrouble-redirecterrors]
* If you are installing a 3.0 agent for build 3 from OpenSSO,
here are some [instructions to install OpenSSO Glassfish Agent 3.0 build 3 | b3agentinstallinstruction]

* If you are installing a 3.0 agent for build 2 from OpenSSO,
here are some [instructions to install OpenSSO Glassfish Agent 3.0 b2 | b2agentinstallinstruction]