Enabling IP/Resource/Environment Based Authentication With OpenSSO: Part 1, Introduction

[Part 1] [Part 2] [Part 3]

The OpenSSO server offers web access management and single sign-on (SSO) capabilities. OpenSSO protects your web applications and services through a core set of access controls based on authentication and policy services. You can prevent unauthorized access to your application first by installing OpenSSO Policy Agents (Web agents or Java EE agents) on the web containers or application containers that host your application, then by defining authentication and authorization policy configurations on the OpenSSO server.

This article explains how to configure the OpenSSO server and Policy Agents to use IP/Resource/Environment-based authentication. This feature provides a flexible mechanism to define customized policies and greatly improved user experience for access control using OpenSSO.

Although it is not elsewhere mentioned in this article, the IP/Resource/Environment-based authentication feature also works with the Distributed Authentication service and the authentication client SDK (com.sun.identity.authentication.AuthContext).

This article assumes that you are familiar with the basics of OpenSSO services (especially Authentication and Policy services) and Policy Agents, and that you have installed them on your system.

Overview

OpenSSO Policy Agents (Web or Java EE agents) use a two-phase process for restricting access to web resources.

The first phase is authentication. In this phase, OpenSSO Policy Agents redirect application users to OpenSSO for a default authentication scheme defined in the OpenSSO server's authentication configuration. This phase obtains the first valid SSOToken from the OpenSSO server.

The second phase is authorization, which occurs after authentication. In the authorization phase, OpenSSO agents contact the OpenSSO server to determine whether or not the user is entitled to access the protected resource. The OpenSSO server's Policy service makes its decision based on two sources of information: policies, which are a set of rules that are defined for the protected resource, and user context (known as policy subject). Additional policy conditions such as the authentication scheme and environment settings (IP address, time of day, and so on) contribute to decision making. If these authorization conditions are not satisfied, policy conditions are delivered to the OpenSSO agents as policy advices.

Because enforcing access to web resources is a two-stage process, two passwords may be required for a user to access a protected resource. Consider an example in which the default authentication scheme for the OpenSSO server is LDAP, and the policy condition defined for accessing a web application is Safeword. In this example, the user is first prompted for the LDAP password in order to pass the authentication phase, then is prompted for the Safeword password in order to pass the authorization phase. User experience would be enhanced by having only one password that satisfied both the authentication and authorization requirements.

An existing solution to the problem uses a separate Gateway servlet for resource authentication. The Gateway servlet is not integrated with the authentication endpoint (the Login servlet). This solution has some other limitations such as limited policy condition support, inability to work with a distributed authentication component, and inability to handle federation use cases.

An IP/Resource/Environment-based authentication design solves the problem while overcoming the limitations of the Gateway servlet approach. With this design, a login servlet is the integrated single entry point for all types of authentication. The user is prompted for all authentication credentials in the first phase. The design also provides policy condition and advice support for various client environment parameters such as client IP address, client locale, and so on.

Downloads and Installation

You can download OpenSSO server and Policy Agent software from the following URLs. Installation instructions accompany the downloads.

• OpenSSO server
  
  
  • OpenSSO Express build 8 or above

• OpenSSO Policy Agents, including:
  
  
  • OpenSSO Web Agents 3.0
  • OpenSSO JavaEE Agents 3.0

Architecture

Figure 1 illustrates the resource authentication architecture and information flow.

Figure 1: Resource Authentication Architecture and Information Flow

The numbered paragraphs in the following discussion refer to the numbered flows in Figure 1.

1. A client browser sends a request for the protected resource to the deployment container (such as a Web server or an application server) protected by the Policy Agent.
   
   
2. The OpenSSO Policy Agent intercepts the request. Depending on the agent's configuration and deployment, it redirects the request either to a distributed authentication UI or to a server-side authentication service.
   
   
3. Distributed authentication UI or authentication server-side UI is accessed with resource=true&goto=<application/resource URL> query parameters.
   
   
1. Resource-based authentication is initialized through the authentication client SDK, with a statement of the following form:
   AuthContex ac = new AuthContext(<realm name>); ac.login(AuthContext.IndexType.RESOURCE, <resource/application URL>, params, environmentMap);
   
   
2. Request/Response data is exchanged in XML format over HTTP(s) between the authentication client SDK and the authentication service.
   
   
4. The authentication service sends a query to the policy service, which returns results (allow/deny or advice) based on the protected resource's URL and the client's environment parameters. The resource's URL is obtained from the query parameter resourceURL or goto if the resourceURL parameter is not present. The client's environment parameters are obtained from query parameters and headers of the HTTP request.
   
   
5. The authentication service prompts the authentication scheme based on advice from the policy service. The user completes authentication process.
   
   
6. The authentication service redirects the user to the agent-protected application.
   
   
7. The agent validates policy enforcement satisfaction with the policy service by presenting the user's valid OpenSSO session token through the policy client SDK.
   
   
8. The user is granted access to the application.

The sequence of events is summarized in the diagram of Figure 2.

Figure 2: Resource Authentication Sequence Diagram

Figures 1 and 2 illustrate that, in cases where IP/Resource/Environment-based authentication is used, the authentication service depends on the policy service to determine the required authentication type. When invoking the policy service, the authentication service passes down the resource name and client environment variables that have been defined in the HTTP request parameters and request headers. The OpenSSO policy service evaluates the configured policy condition(s) and returns the condition decision in the form of a message (allow, deny, or advice) to indicate which authentication type to call. The user is then prompted for credentials for the required authentication type and, if successful, continues with rest of the authentication process.

As part of the implementation, a new authentication type named RESOURCE has been added, parallel to the level/role/service/user/realm-based authentication type. With the RESOURCE type, the required authentication type is not fixed; rather, the type can vary based on the IP, resource, and environment setting. Because resource authentication is based on environment variables, the RESOURCE type ultimately runs one of the other configured authentication types rather than running a fixed authentication process of its own.

The invocation of the IP/Resource/Environment-based authentication could be dynamic. The client can pass down the query parameter ?resource=true to UI/Login to indicate that the new IP/Resource/Environment-based authentication is required. In this way, other types of authentication — for example, module/level — can be allowed at the same time.

Creating Policies for Protected Resources

To use resource authentication, you need to create a policy for the protected resource. The policy must specify a Resource/Environment/IP address condition that defines the authentication process for various client environment parameters. If there is no policy defined for the protected resource, the user is prompted from the default authentication process defined for the realm.

A new policy condition plug-in implementation named Resource/Environment/IP Address has been designed to define IP/Environment conditions and authentication type advice. This new policy condition can be added to any policy definition, as described below.

Adding a Policy Condition to a Policy Definition

To add the Resource/Environment/IP Address policy condition to a policy definition, follow these steps:

1. Log in to the OpenSSO Console as user amadmin at a URI with the following syntax:
   
   <openssoserver_protocol>://<openssoserver_host>:<openssoserver_port>/<openssoserver_deploy_uri>
   
   For example:
   
   http://localhost:8080/opensso/
   
   
2. Navigate to Access Control –> Top Level Realm –> Policies, and click New Policy, as shown in Figure 3.
   
   
   
   Figure 3: OpenSSO Console
   
   
3. Enter envPolicy as the policy name, as shown in Figure 4. Click the Yes checkbox to make the policy active. Click OK.
   
   
   
   Figure 4: Creating a New Policy
   
   
4. Under Conditions, click New. Click the Resource/Environment/IP Address condition button, as shown in Figure 5. Click Next.
   
   
   
   Figure 5: Selecting Condition Type
   
   
5. Enter the Name and the Environment condition values as required by the Use Cases described in Parts 2 and 3. Then, click Finish to create the Resource/Environment/IP Address condition.

[Part 1] [Part 2] [Part 3]