Protecting a Web Site With OpenAM

This guide shows you how to quickly set up OpenAM and get started with access management. In reading and following the instructions in this guide, you will learn how to protect a Web page using OpenAM and a Web policy agent.

About OpenAM

OpenAM provides a service called access management, which manages access to resources, such as a web page, an application, or a web service, available over the network. Once it is set up, OpenAM provides an infrastructure for managing users, roles, and access to resources. In this chapter, you manage access to a single web page.

OpenAM centralizes access control by handling both authentication and authorization. Authentication is the process of identifying an individual, for example, by confirming a successful login. Authorization is the process of granting access to resources to authenticated individuals.

OpenAM centralizes authentication by using a variety of authentication modules that connect to identity repositories that store identities and provide authentication services. The identity repositories can be implemented as LDAP directories, relational databases, RADIUS, Windows authentication, one-time password services, and other standards-based access management systems.

OpenAM lets you chain together the authentication services used. Authentication chains let you configure stronger authentication for more sensitive resources for example. They also let you set up modules that remember a device when the user logs in successfully. Or that evaluate the risk given the login circumstances and therefore can require more credentials when a user is logging in from an unusual location. This chapter uses OpenAM’s built-in identity repository and authentication modules to make it easier to get started.

OpenAM centralizes authorization by letting you use OpenAM to manage access policies separate from applications and resources. Instead of building access policy into a web application, you install a policy agent with the web application to request policy decisions from OpenAM. This way you can avoid issues that could arise when developers must embed policy decisions into their applications. With OpenAM, if policy changes or an issue is found after the application is deployed, you have only to change the policy definition in OpenAM, not deploy a new version of the application. OpenAM makes the authorization decisions, and policy agents enforce the decisions on OpenAM’s behalf.

The rest of this chapter has you demonstrate OpenAM access management by installing OpenAM, creating a policy, and installing a policy agent on a web server to enforce the policy for a web page.

Software Requirements To Try Out OpenAM

The only software you need to install is Docker. If you don’t have Docker on your computer follow the instructions from the following link: https://docs.docker.com/get-started/get-docker/#supported-platforms.

You will learn how to run OpenAM docker container, and how to install OpenAM Apache Policy Agent for the Apache HTTP Server.

Setting Up the Software

This section includes the following procedures that detail how to set up OpenAM to protect a web page:

The procedures in this section are written for use on a Linux system. If you are running Microsoft Windows, adapt the examples accordingly.

To Prepare Your Hosts File

OpenAM requires that you use fully qualified domain names when protecting web resources. This is because OpenAM uses HTTP cookies to keep track of sessions for single sign-on (SSO), and setting and reading cookies depends on the server name and domain.

You can get started with OpenAM without setting up separate systems for each fully qualified domain name. Give your system openam.example.com and www.example.com aliases by editing your hosts file.

Alternatively, if you already have a DNS set up, you can use that instead of your hosts file.

  • Add the aliases to your hosts file using your preferred text editor.

    $ sudo vi /etc/hosts
Password:

### Edit /etc/hosts ###

$ cat /etc/hosts | grep openam
127.0.0.1    localhost openam.example.com www.example.com
To Install OpenAM

Create a Docker network for OpenAM.

$ docker network create openam-quickstart

Run the OpenAM Docker image.

$ docker run -h openam.example.com -p 8080:8080 --network openam-quickstart --name openam openidentityplatform/openam

You can access the web application in a browser at http://openam.example.com:8080/openam/.

  1. Browse to OpenAM in this example, http://openam.example.com:8080/openam/, to configure the application.

  2. On the OpenAM home page, click Create Default Configuration.

    openam home page

  3. Review the software license agreement. If you agree to the license, click "I accept the license agreement", and then click Continue.

    openam license default

  4. Set the Default User [amAdmin] password to changeit and the Default Policy Agent [UrlAccessAgent] password to secret12, and then click Create Configuration to configure OpenAM.

    openam default configuration

    If you were configuring OpenAM for real-world use, you would not use either of those passwords, but this is only to get started with OpenAM. The amadmin user is the OpenAM administrator, who is like a superuser in that amadmin has full control over the OpenAM configuration.

  5. Click the Proceed to Login link, then log in as amadmin with the password specified in the previous step, changeit.

    After login, OpenAM should direct you to the Realms page.

    openam realms

    OpenAM stores its configuration, including the embedded OpenDJ directory server in the folder named ~/openam/ in your home directory. The folder shares the same name as your server instance. It also has a hidden folder, ~/.openamcfg/, with a file used by OpenAM when it starts up. If you ruin your configuration of OpenAM somehow, the quickest way to start over is to stop Tomcat, delete these two folders, and configure OpenAM again.

    The OpenAM core server and OpenAM Console are now configured. Make sure you have successfully logged in to OpenAM Console before you proceed.

To Configure a Policy in OpenAM

OpenAM authenticates users and then makes authorization decisions based on access policies that indicate user entitlements. Follow these steps to create a policy that allows all authenticated users to perform an HTTP GET (for example, to browse) the Apache HTTP home page that you set up earlier.

  1. In the OpenAM console, select the Top Level Realm on the Realms page.

    OpenAM allows you to organize identities, policies, and policy agent profiles into realms as described in "Configuring Realms" in the Administration Guide. For now, use the default Top Level Realm.

  2. On the Realm Overview page, navigate to Authorization > Policy Sets > Default Policy Set > Add a Policy.

    gsg policies add a new policy

    For more information on the relationship between realms, policy sets, and policies, see "About Authorization in OpenAM" in the Administration Guide.

  3. On the New Policy page, enter the following data:

    1. In the Name field, give your new policy the name Authenticated users can get Apache HTTP home page.

    2. On the Resource Type drop-down list, select URL.

    3. On the Resources drop-down list, select the URL pattern for your policy. In this example, select ://:*/, then enter the resource URL: http://www.example.com:8000/, and then click Add.

      gsg policies new policies settings

    4. Click Create to save your settings.

      gsg policies new settings

  4. On your policy page, select the Actions tab, and then enter the following information:

    1. On the Add an action drop-down list, select GET.

    2. On the Add an action drop-down list, select POST.

    3. Save your changes.

      gsg policies actions

  5. On your policy page, navigate to Subjects and enter the following data:

    1. On the All of drop-down list, review the list and select All of…​.

    2. On the Type section, click the Edit icon. On the Type drop-down list, select Authenticated Users, and then click the checkmark.

    3. Save your changes.

      gsg policies subjects

  6. Review your configuration. To make changes to the configuration, click the relevant tab and amend the configuration.

Next, you must create a web policy agent profile before installing the agent in Apache HTTP Server to enforce your new policy.

To Create a Web Policy Agent Profile

OpenAM stores profile information about policy agents centrally by default. You can manage the policy agent profile through OpenAM Console. The policy agent retrieves its configuration from its OpenAM profile at installation and start up, and OpenAM notifies the policy agent of changes to its configuration. Follow these steps before installing the policy agent itself.

  1. In OpenAM Console, browse to Realms > / Top Level Realm > Applications > Web Agents, and then click New in the Agents table.

  2. In the page to configure your new web policy agent, set the following values.

    Name

    WebAgent

    Password

    password

    Configuration

    Keep the default, Centralized

    Server URL

    http://openam.example.com:8080/openam

    Agent URL

    http://www.example.com:8000

    8000 is the port number you set previously for Apache HTTP Server.

    web agent profile

  3. Click Create to save the new web policy agent profile in OpenAM.

    Next, install a policy agent in Apache HTTP Server to enforce your new policy.

To Install OpenAM Web Policy Agent

Create a Dockerfile on your machine folder with the following contents:

FROM httpd:2.4.34

ENV PA_PASSWORD secret12

#Install pre-requisite packages
RUN echo "deb [trusted=yes] http://archive.kernel.org/debian-archive/debian/ jessie main" >> /etc/apt/sources.list

RUN apt-get update || true

RUN apt-get install -y curl unzip

#Install OpenAM Apache Agent
RUN curl -L -o /tmp/Apache_v24_Linux_64bit_4.1.1.zip https://github.com/OpenIdentityPlatform/OpenAM-Web-Agents/releases/download/4.1.1/Apache_v24_Linux_64bit_4.1.1.zip

RUN unzip /tmp/Apache_v24_Linux_64bit_4.1.1.zip -d /usr/

RUN rm /tmp/Apache_v24_Linux_64bit_4.1.1.zip

RUN echo $PA_PASSWORD > /tmp/pwd.txt

RUN cat /tmp/pwd.txt

RUN cat /etc/issue

#Configure OpenAM Apache Agent
RUN /usr/web_agents/apache24_agent/bin/agentadmin --s "/usr/local/apache2/conf/httpd.conf" "http://openam.example.com:8080/openam" "http://example.com:80" "/" "WebAgent" "/tmp/pwd.txt" --acceptLicence --changeOwner

Build Apache Docker image with the preconfigured OpenAM Apache Policy Agent.

docker build --network=host -t apache_agent -f Dockerfile .

Run the image:

docker run -it --name apache_agent -p 8000:80 -h www.example.com --shm-size 2G --network openam-quickstart  apache_agent

=== Trying It Out

Now that you have completed the steps above, you can access the protected web page to see OpenAM at work.

  1. Log out of OpenAM Console.

  2. Browse to http://www.example.com:8000 to attempt to access the Apache "It works!" page.

    At this point, the policy agent intercepts your request for the page. Your browser does not return a cookie indicating an OpenAM session, so the policy agent redirects you to OpenAM to authenticate.

  3. Log in as the built-in default OpenAM demonstration user demo with password changeit.

    openam login

    On successful login, OpenAM sets a session cookie named iPlanetDirectoryPro in your browser for the domain .example.com. The cookie is then returned to servers in the example.com domain, such as openam.example.com and www.example.com.

    If you examine this cookie in your browser, you see that it has a value, such as AQIC5wM2LY4SfcwciyfvJcQDUIB7kIWEH187Df_txqLdAVc.AAJTSQACMDEAAlNLABMxMDYwNzY1MjQ0NTE0ODI2NTkx. This is the SSO Token value. The value is in fact an encrypted reference to the session that is stored only by OpenAM. So, only OpenAM can determine whether you are actually logged in, or instead, that the session is no longer valid and you need to authenticate again.

    The OpenAM session is used for SSO. When the browser presents the cookie to a server in the domain, the agent on the server can check with OpenAM using the SSO Token as a reference to the session. This lets OpenAM make policy decisions based on who is authenticated, or prompt for additional authentication, if necessary.

    Your SSO session can end in a few ways. For example, when examining the cookie in your browser, you should notice that it expires when the browser session ends (when you shut down your browser). Alternatively, you can log out of OpenAM explicitly. Sessions can also expire. OpenAM sets two limits, one that causes your session to expire if it remains inactive for a configurable period of time (default: 30 minutes), and another that caps the session lifetime (default: 2 hours).

  4. After successful login, you are redirected to the Apache "It works!" page.

    web server home page

    In the background, OpenAM redirected your browser again to the page you tried to access originally, http://www.example.com:8000. This time, the web policy agent intercepted the request and found the SSO Token so it could request a policy decision from OpenAM regarding whether the user with the SSO Token has access to get http://www.example.com:8000/. OpenAM replied to the policy agent that it could allow access, and the policy agent allowed Apache HTTP Server to send back the web page.

Congratulations on protecting your first web site with OpenAM! Notice that you had only to install software and to configure OpenAM. You did not have to change your web site at all in order to add SSO and to set up access policies.

OpenAM can do much more than protect web pages. Read the next chapter to learn more.

=== Trying Out Stateless Sessions

In the "Trying It Out" section, you successfully configured OpenAM and viewed the iPlanetDirectoryPro session cookie. The session cookie contains information for OpenAM or a policy agent to locate the session data object on the server from which the session originated. Sessions that are stored in a server’s memory are called stateful, which is the default configuration at the realm level.

OpenAM also supports stateless sessions, in which the authenticated user’s session is stored on the client-side (for example, in a browser), not in memory. The session cookie cannot be updated until the session ends, when the user logs out or the session expires.

To try out stateless sessions, see "Configuring Session State" in the Administration Guide.