Chapter 9. Configuring Single Sign-On within One Domain
Prev |  | Next

# Chapter 9. Configuring Single Sign-On within One Domain

This chapter describes the configuration of Single Sign-On (SSO) services for multiple resources on one domain. To understand how SSO works, you need to understand some key elements of the HTTP cookie, as described in RFC 6525, HTTP State Management Mechanism.

With SSO a user can access multiple independent services from a single session.

## 9.1. The Basics of the HTTP Cookie

Within an HTTP cookie, you can store a single custom ``name`=`value`` pair, such as ``sessionid`=`value``. Other custom names within a cookie are as follows.

Domain

  Normally set to the domain from where the cookie was issued. To work with multiple subdomains, the `Domain` should be set to a URL like `Domain``=example.net`. This is also known as the cookie domain, as defined in the Configuration Reference chapter of the Reference document. A cookie domain set to `example.net` will work for subdomains such as `app1.example.net` and `service1.example.net`.

Path

  The directory in the URL to which the cookie applies. If the `Path` `=/openam`, the cookie applies to the `/openam` subdirectory of the FQDN, and lower level directories, including `openam/UI` and `openam/UI/Login`.

Secure

  If the `Secure` name is included, the cookie can be transferred only over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

HttpOnly

  When the `HttpOnly` name is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the noted flag "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (such as a web browser API that exposes cookies to scripts)."

Expires

  The lifetime of a cookie can be limited, with an `Expires` name configured with a time, based on UTC (GMT).

### Note

Be careful. Do not take a shortcut with a top-level domain. Web browser clients today are designed to ignore cookies set to top-level domains including `com`, `net`, and `co.uk`. In addition, a cookie with a value like `Domain`= `app1.example.net` will not work for similar subdomains such as `app2.example.net`.

## 9.2. Cookies and the SSO Session Process

OpenAM uses cookies to track user sessions. The diagram shown next illustrates how OpenAM assigns and tracks cookies.

In the diagram:

- The domain shown in the description is `example.net`

- The protected resource application can be found on `app.example.net`

- The OpenAM server is located on `sso.example.net`.

[D]

A client points his browser to a protected resource application. An agent on the application checks the client browser cookies for the presence of a session ID, a component of an SSO Token. If such a Session ID exists and is valid, the agent requests validation (see arrow 8).

If no valid session ID currently exists, the agent redirects the client to OpenAM for authentication (AuthN). The client is then sent to OpenAM for AuthN. If the client submits valid credentials, the AuthN service creates a session cookie. The SSO Token and configured domain name is embedded in that cookie. OpenAM issues an HTTP redirect to send the client browser back to the protected resource. The SSO Token is actually a Java Object.

The agent then verifies the validity of the session with the OpenAM session service, before granting access.

## 9.3. Potential Problems

In general, problems with SSO relate to some sort of mismatch of domain names. For example, a cookie that is configured on a third-level domain such as `sso.example.net` will not work with an application on a similar domain such as `app.example.net`. Even if the Session ID is valid, the application will not receive the SSO Token. The request is then redirected to OpenAM. The client gets what appears as a SSO Token in the diagram, which is actually a valid SSO tracking cookie that redirects immediated, and the cycle continues. Other issues that may lead to similar problems are shown here.

- When a cookie domain does not match a domain for the protected application

  Assume the application is configured on a domain named `example.org`. That application will not receive an SSO Token configured on the `example.net` domain.

- When a third-level domain is used for the SSO Token

  If an SSO Token is configured on `sso.example.net`, an application on `app.example.net` does not receive the corresponding cookie. In this case, the solution is to configure the SSO Token on `example.net`.

- When the `Secure` flag is used with a regular HTTP application

  If you need encrypted communications for an application protected by OpenAM, use the `Secure` flag and make sure the application is accessible over HTTPS.

- When the path listed in the cookie does not match the path for the application

  Perhaps the cookie is configured with an `/helloworld` path; that won't match an application that might be configured with an `/hellomars` path. In that case, the application will not receive the cookie.

- When an inappropriate name is used for the cookie domain

  As noted earlier, client browsers are configured to ignore first-level domains such as `com` and `net` as well as functional equivalents such as `co.uk` and `co.jp`.

- When working with different browsers

  The ``name``=``value`` pairs described earlier may not apply to all browsers. The requirements for an HTTP cookie sent to an IE browser may differ from the requirements for other standard browsers such as Firefox and Chrome. Based on anecdotal reports, IE does not recognize domain names that start with a number. In addition, IE reportedly refuses cookies that include the underscore (_) character in the FQDN.

## 9.4. Configure SSO on One Domain

Now that you have read about the SSO process, you should be able to set it up on a server configured with OpenAM and a web service protected by an OpenAM agent. The following procedure assumes that you know how to configure OpenAM, the Apache Web server, and associated OpenAM Apache agent.

Procedure 9.1. Configure SSO on One Domain

1. Install OpenAM as described in the OpenAM Installation Guide. This procedure uses a Server URL of `http://openam.example.net:8080/openam`.

2. Install the appropriate policy agent, as described in the OpenAM Web Policy Agent Installation Guide or OpenAM Java EE Policy Agent Installation Guide. This procedure uses an agent URL of `http://app.example.net:80`, and an agent name of `webagent1`.

3. Make sure that both URLs are configured with IP addresses, as described in the chapter on Installing OpenAM Core Services.

4. Return to the OpenAM server on `http://openam.example.net:8080/openam`. Log in as the administrative user, normally `amadmin`. To activate and configure the agent, follow the procedure described in the OpenAM Web Policy Agent Installation Guide or OpenAM Java EE Policy Agent Installation Guide.

5. Now you can configure SSO Only mode. In the OpenAM console, click Access Control > `Realm Name` > Agents > `webagent1`. Scroll down to SSO Only Mode and activate the Enabled box.

6. Save your changes.

7. Make sure you have configured the SSO domain, in this case, `example.net`. Click Configuration > System > Platform. Make sure `example.net` (or your chosen domain) is selected as a cookie domain.

8. Save your changes.

9. Restart the web server. The agent should be active. You should now be able to log out of the OpenAM server.

10. Verify the agent URL, in this case, `http://app.example.net`. The OpenAM web agent should now redirect requests to the OpenAM server.

If you want to configure OpenAM and an application on two different cookie domains, such as `example.org` and `example.net`, you will need to set up Cross-Domain SSO (CDSSO). For more information, see the chapter on Configuring Cross-Domain Single Sign On.

Prev |  | Next
Chapter 8. Configuring Password Reset | Home | Chapter 10. Configuring Cross-Domain Single Sign On