Now that everything has been installed onto openam-server it is time to set it up and turn it into a functional distribution. This section of the guide describes the process of setting up the OpenAM deployment, from first configuration, to the point where we are choosing which users will have access to which website resources.
The OpenAM custom configuration process allows lots of common configuration options to be set with ease, so while taking more effort before getting into the configuration pages, it saves configuring the server at a later date.
After choosing the Create New Configuration option, the first step is to choose password for the default administrator account (amAdmin). The password needs to be at least 8 characters long. We will use the password 'cangetinam'. Once a valid password has been entered twice, the next button will appear and the configuration can proceed.
On the server settings page, the Server URL and the Configuration Directory both need some attention. By default the Server URL will be the address that was typed to reach the server. The problem with this being that it requires a fully qualified domain name, so if the page was accessed via localhost or an IP Address it will cause problems. This is why it was configured to be accessible at openam.example.com.
The other setting on this page to take note of is the Configuration Directory. It is important that the user that Apache Tomcat is running under has write access to that directory. As a result ~/openam/config is appropriate for this purpose.
Supported Platform Locales are en_US (English), de (German), es (Spanish), fr (French), ja (Japanese), zh_CN (Simplified Chinese), or zh_TW (Traditional Chinese).
The Configuration Data Store Settings do not need to be changed when working with a single server configuration.
The User Data Store Settings are what connect OpenAM to the OpenDJ data store. The side effect of this is that most of these settings require some attention. Fields which require changing are marked with an Asterisk (*).
*User Data Store Type : OpenDJ
SSL/TLS Enabled : Not ticked
*Directory Name : openam.example.com
*Port : 1389
*Root Suffix : dc=example,dc=com
Login ID : cn=Directory Manager
*Password : cangetindj
The configurator does not give the option to continue until all the settings have been correctly specified and it has successfully connected to the OpenDJ instance.
OpenAM is not installed behind a load balancer in this test deployment, so Site Configuration can be left as default.
The policy agent password once again needs to be 8 characters or more and it must also be different from the administrator password. In this case we will use 'cangetinpa', although the policy agent user is not used in this tutorial.
The Summary Page shows a brief summary of the settings that were defined in the previous few steps before the configuration is created. Clicking Create Configuration will begin the configuration process.
The Configuration Progress Screen will display the progress of the installation and take a couple of minutes to run through. All of the output on this screen, as well as any errors, are written to the file~/openam/config/install.log. Assuming success a Configuration Complete! view will appear, providing a link to the login page.
In the case that it did not succeed check the troubleshooting guide at https://wikis.forgerock.org/confluence/display/openam/Common Install Issues.
Now that the server is running the next step is to login with the user 'amAdmin' and the password 'cangetinam' and begin diving into the web administration interface. The first tab provides a list of common tasks, providing for easier setup of OpenAM when integrating with certain web service. The second tab is the one that we are going to be performing most of our configuration in.
Within the Access Control tab, it will list realms. In complex deployments these provide more access controls between different resources and user data sources, and even in simple ones it is best practice to create a sub-realm. However for this tutorial we will use the Top Level Realm. Clicking on the link will open up the realm configuration pages, with a new set of tabs relating specifically to the realm. Some of the configuration for this will already have been done by the quick configuration process, providing an OpenDJ configuration under Data Stores and the Policy Configuration under Services.
At this point we want to create some users for the system. This is done in the Subjects tab. In here it will be possible to see the amAdmin user and an anonymous user. Click New... to create a new user and then fill out all the details in the form.
ID : user001
First Name : User
Surname : One
Full Name : User One
Password : firstuser
Confirm Password : firstuser
User Status : Active
Now add another three users to the database.
It is worth noticing the Group tab that appears within the Subjects tab, because while we are not creating or configuring any groups here, it is worth coming back to experiment with them after the tutorial.
Checking the OpenDJ User Data Store
Having created some users, they should be stored in OpenDJ. You can query OpenDJ directly using the following ldapsearch command:
Alterntively, if you have access to a X session, you can open up the OpenDJ control-panel by running the command:
Once the splash-screen has passed, it will ask you for the password to the local OpenDJ datastore, which is 'cangetindj', and select Ok to log in. This control panel provides various pieces of information about the running OpenDJ server, such as whether it is running, what services are active, and which ports they are mapped to.
As we want to look at the data contained within the directory, click on Manage Entries. This will bring up the Manage Entries window. Expanding the tree on the left will reveal a number of sub-trees, including opensso adminusers and people. Expanding the people tree should show the newly created users, and selecting one of them should show the details relating to them.
Creating A Web Agent
The next step is to make an Agent Profile in the Agent tab for the realm. The Agent Profile holds the settings for the Web Policy Agent, which is the part of OpenAM that gets installed on the web server, in order to provide the configuration. Click on the New... button under the agent section.
Going back into the Agents page, it is now possible to see the newly created agent. Opening the webagent shows all the default settings which were applied in creating the agent. Although it is not recommended, it is possible to skip the need for an access policy by selecting the 'SSO Only Mode' tick box, that will bypass any policies and automatically allow access to all resources hosted on the website-server to anyone who is logged into OpenAM.
It is also worth adding a 'Logout' option for the standard domain. In order to do this open the web agent and select the OpenAM Services tab. Scroll down to the Agent Logout URL section and in the text box below the Logout URL List, add the page http://website.example.com/logout.html.
Creating An Access Policy
The final step to configuring the OpenAM server is creating an access policy. This is done within the Policies tab of the realm configuration. Select the New Policy... button and a blank policy page will be displayed. Each policy will apply a set of rules to a set of subjects (users or groups), potentially in a given set of conditions. These rules can then allow (or deny) access to certain resources held on the web server.
Create a new Rule for the policy, and choose a URL Policy Agent, to create an access policy for web resources.
Name : URLPolicy
Actions : Select and allow both GET and POST
The wildcard '*' in policy URLs does not match '?'. As such if you wish to allow GET parameters to be submitted then a second policy foris required.
Next set up the subjects for the Policy. Of the three choices when selecting a subjects agent, we want to work with the OpenAM Identity Users, which are the Users and Groups that have been created in the Subjects tab for the realm. The Authenticated Users option applies the policy to all users with an active login session in OpenAM, and is as such discouraged.
Name : UserAccess
Exclusive : Not ticked
Now filter on users and click on search. Add users user001 and user002 into the selected column, while leaving user003 and user004 as available. Save and exit the subject policy, before doing the same in the main policy page. Having completed this, the server should now be fully configured and ready to provide authentication services to your website, once it has been configured.