h1. Getting Started with OpenSSO and Policy Agents
This is a rough draft of an unofficial tutorial to get you started with OpenSSO and policy agents.
Technologies used:
* GlassFish as the application server
* OpenSSO 8.0
* OpenSSO Policy Agent 3.0 for GlassFish
If you are using another server, this will serve 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]
This is a work in progress.
Coming soon: we will add a "getting started" learning path for federation. [Getting Started with Federation | getfed]
h3. 0-a. Create some Fully Qualified Domain Names (FQDN)
The AM/FAM/OpenSSO server and policy agents require FQDNs 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 must use FQDNs in your URLs - for example, my.test.domain.com in http ://my.test.domain.com:6948/opensso . You must use an FQDN for all URL values you use in agent installers etc.
Set up an 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]
h3. 0-b. Create two application server instances/domains
On an application server, you can create separate instances or called domains where each domain is isolated from the other. Each domain would have its own ports and you could deploy apps on them. This is important, because you are going to deploy opensso.war on one domain, and the opensso agent on a second domain. This second domain is also where you will deploy your applications and sample applications which the agent will protect.
So now create the two domain instances. GlassFish comes with one pre-made domain called *domain1* already and it uses port 8080. 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 we would access it at http://my.test.domain.name:8080 Please remember to always use a hostname like my.test.domain.name and not localhost, otherwise things won't work.
Since GlassFish already has a domain called domain1, we will make use of it. This is where I suggest you deploy the opensso.war in step 2.
We need to create a second domain, where we will install the agent and deploy our sample applications. For this example, we will use the name "domain2". It is fairly easy to create a new domain using GlassFish. This is also handy, because sometimes if an agent installation goes bad, it is easy to just create another domain and reinstall the agent.
The command you will use will be similar to the following:
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 your exact GlassFish 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 nightly builds of 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. There are also non-Java Agents such as for Apache httpd and MS IIS.
In this tutorial we will focus on the GlassFish agent, though the steps are roughly the same for any of the app servers.
[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, unzip it under some directory like C:\myagents\ and then explore the unzipped agent download a bit.
h5. 3-b Create an Agent Profile
As described in the policy agent docs, you need to create an agent profile. This is created actually on the opensso.war console UI. On the OpenSSO server, you need to create a profile for the agent which you will install next. This profile will contain the URL of the agent and some basic info, and it will also generate some default properties for your agent's behaviour. Once installed, you will use the OpenSSO server UI to manage your agents. But first you need to create a profile for the agent. Make sure the URLs you enter when creating the agent match the urls of the agent domain and its ports for the domain where you will install the agent. And use Fully Qualified Domain Names!
The steps for this are available in the [offical documents for agents 3.0 | http://docs.sun.com/app/docs/doc/820-4578/gfxjk?a=view]
h5. 3-b. Install agents
In this step you will install the agent. Remember, we will install the agent on domain2 (the second domain, separate from where OpenSSO is deployed). Here are some important tips when you install the agent:
* Keep the GlassFish domain where you deployed opensso.war running. The agent installer will talk to the OpenSSO server, but if it is not available then some of the validation that helps ensure a proper agent configuration will fail
* Stop the domain where you will install agent. The command for this is "asadmin stop-domain domain2". The reason we stop it is that the agent installer will edit some of the config files for that domain of the application server, and some OS versions like windows, won't let edits happen when something is running. This often causes problems so please remember to stop this domain where you plan to install the agent.
* Remember which domain has the agent and which has opensso.war, and remember their URLs and ports because you will use that info in later installations.
Now for the installation, you can see the longer version of installation in official docs, or use the shortcut we show which is just a copy of the output of questions and the answers you will provide on the command line installer.
The official docs of interest if you want longer explanations are
* [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 contains 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 the mini-sample app. The article details the steps and shows screen shots and has some explanations of 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 mini-application as part 1 of this article series, so is an easy step after the first article. It shows how to protect certain pages and also how to make some pages like a 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 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 out 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 denied 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 how a web app using J2EE declarative security (web.xml security elements) and a simple web application (no security specified 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 OpenSSO 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]
This is a rough draft of an unofficial tutorial to get you started with OpenSSO and policy agents.
Technologies used:
* GlassFish as the application server
* OpenSSO 8.0
* OpenSSO Policy Agent 3.0 for GlassFish
If you are using another server, this will serve 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]
This is a work in progress.
Coming soon: we will add a "getting started" learning path for federation. [Getting Started with Federation | getfed]
h3. 0-a. Create some Fully Qualified Domain Names (FQDN)
The AM/FAM/OpenSSO server and policy agents require FQDNs 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 must use FQDNs in your URLs - for example, my.test.domain.com in http ://my.test.domain.com:6948/opensso . You must use an FQDN for all URL values you use in agent installers etc.
Set up an 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]
h3. 0-b. Create two application server instances/domains
On an application server, you can create separate instances or called domains where each domain is isolated from the other. Each domain would have its own ports and you could deploy apps on them. This is important, because you are going to deploy opensso.war on one domain, and the opensso agent on a second domain. This second domain is also where you will deploy your applications and sample applications which the agent will protect.
So now create the two domain instances. GlassFish comes with one pre-made domain called *domain1* already and it uses port 8080. 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 we would access it at http://my.test.domain.name:8080 Please remember to always use a hostname like my.test.domain.name and not localhost, otherwise things won't work.
Since GlassFish already has a domain called domain1, we will make use of it. This is where I suggest you deploy the opensso.war in step 2.
We need to create a second domain, where we will install the agent and deploy our sample applications. For this example, we will use the name "domain2". It is fairly easy to create a new domain using GlassFish. This is also handy, because sometimes if an agent installation goes bad, it is easy to just create another domain and reinstall the agent.
The command you will use will be similar to the following:
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 your exact GlassFish 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 nightly builds of 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. There are also non-Java Agents such as for Apache httpd and MS IIS.
In this tutorial we will focus on the GlassFish agent, though the steps are roughly the same for any of the app servers.
[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, unzip it under some directory like C:\myagents\ and then explore the unzipped agent download a bit.
h5. 3-b Create an Agent Profile
As described in the policy agent docs, you need to create an agent profile. This is created actually on the opensso.war console UI. On the OpenSSO server, you need to create a profile for the agent which you will install next. This profile will contain the URL of the agent and some basic info, and it will also generate some default properties for your agent's behaviour. Once installed, you will use the OpenSSO server UI to manage your agents. But first you need to create a profile for the agent. Make sure the URLs you enter when creating the agent match the urls of the agent domain and its ports for the domain where you will install the agent. And use Fully Qualified Domain Names!
The steps for this are available in the [offical documents for agents 3.0 | http://docs.sun.com/app/docs/doc/820-4578/gfxjk?a=view]
h5. 3-b. Install agents
In this step you will install the agent. Remember, we will install the agent on domain2 (the second domain, separate from where OpenSSO is deployed). Here are some important tips when you install the agent:
* Keep the GlassFish domain where you deployed opensso.war running. The agent installer will talk to the OpenSSO server, but if it is not available then some of the validation that helps ensure a proper agent configuration will fail
* Stop the domain where you will install agent. The command for this is "asadmin stop-domain domain2". The reason we stop it is that the agent installer will edit some of the config files for that domain of the application server, and some OS versions like windows, won't let edits happen when something is running. This often causes problems so please remember to stop this domain where you plan to install the agent.
* Remember which domain has the agent and which has opensso.war, and remember their URLs and ports because you will use that info in later installations.
Now for the installation, you can see the longer version of installation in official docs, or use the shortcut we show which is just a copy of the output of questions and the answers you will provide on the command line installer.
The official docs of interest if you want longer explanations are
* [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 contains 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 the mini-sample app. The article details the steps and shows screen shots and has some explanations of 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 mini-application as part 1 of this article series, so is an easy step after the first article. It shows how to protect certain pages and also how to make some pages like a 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 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 out 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 denied 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 how a web app using J2EE declarative security (web.xml security elements) and a simple web application (no security specified 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 OpenSSO 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]