Sun OpenSSO Enterprise 8.0 Deployment Planning Guide

Chapter 4 Using a Policy Agent and the Client SDK to Integrate Applications with OpenSSO Enterprise

This chapter provides a quick overview of the various ways in which new and existing applications can be integrated with an existing OpenSSO Enterprise deployment for Authentication, Authorization, Auditing and Single Sign-On (AAA) services, Federation, Web Services, Web Services Security and Identity Services.

The following topics are contained in this chapter:

About the OpenSSO Enterprise Client SDK

The OpenSSO Enterprise Client SDK is the core software component that enables you to integrate OpenSSO Enterprise with other applications. The Client SDK is supplied by OpenSSO Enterprise and provides APIs you can use to access each service hosted by the OpenSSO Enterprise server. The following are common ways of using the Client SDK :

Embedded directly in the business logic of a standalone application.
Embedded directly in a container-hosted application such as a .Net or a J2EE application server.
Embedded in the container either directly or using a container-provided security plug-in mechanism.
Embedded in a proxy server installed in front of the protected application.

OpenSSO Enterprise Policy Agents are prepackaged client software that implement options 3 and 4 above.

About the Centralized Policy Agent Configuration

The Centralized Policy Agent Configuration is new in OpenSSO Enterprise 8.0. This feature provides a policy agent interface for managing multiple policy agent configurations from a single, centralized place. The policy agent configurations are stored in the OpenSSO Enterprise data store. A policy agent administrator can use either the OpenSSO Enterprise command-line interface (CLI), or the administration console to manage stored data.

Most policy agent configuration changes are conveyed to the participating policy agents without requiring the policy agents to be restarted. The policy agents respond to the changes based on the nature of the updated properties.

In the Centralized Policy Agent Configuration, policy agent configurations are separated into two sets. One set contains a few policy agent properties that are absolutely required for the policy agent start and to initialize itself properly. A file that contains these properties remains at the local host on which the policy agent is installed. This properties file acts as bootstrapping file for the policy agent.

The other set of policy agent configurations contains all remaining agent configuration properties. These configuration properties are stored either at the local policy agent host, or at a centralized data store managed by the OpenSSO Enterprisebased on the agent configuration repository type.

You can configure OpenSSO Enterprise to store policy agent configurations in a local repository or in a remote repository. A local policy agent configuration repository is a property file that contains all the policy agent configuration data. This option is supported for backward compatibility with legacy deployments. A remote policy agent configuration repository is the newer, more efficient option. When the policy agent configuration is stored in a remote, centralized data store managed by the OpenSSO Enterprise server, during server startup, the policy agent reads the bootstrapping file first to initialize itself. Then the policy agent makes an attribute service request to the OpenSSO Enterprise server to retrieve the policy agent configuration. The policy agent configuration returned by the OpenSSO Enterprise server contains a property that determines the location of the policy agent configuration.

If the property value is centralized, the policy agent uses the configuration just returned. If the property value is local, then the policy agent retrieves the remaining configuration properties from the local policy agent configuration repository and performs its functions accordingly.

The policy agent configuration must be totally stored in either a remote repository or a local repository. Mixed configurations are not supported.

Analyzing the Deployment

The following figure illustrates the deployment architecture for standards-based federated single sign-on using federated web services among independent, trusted partners. The OpenSSO Enterprise Client SDK pictured here includes advanced APIs to enable applications to directly invoke federation features. These APIs are available in the OpenSSO Enterprise Fedlet, a streamlined federation tool. For more information on the OpenSSO Enterprise Fedlet, see Chapter 5, Using the OpenSSO Enterprise Fedlet to Enable Identity Federation.

Figure 4–1 Deployment Architecture for the Client SDK in Federated Single Sign-On

Client SDK, Policy Agents, and OpenSSO Enterprise
server.

The following figures illustrate the process flow among the OpenSSO Enterprise server, the OpenSSO Enterprise policy agent, and the Centralized Policy Agent Configuration components.

Figure 4–2 Process flow for Centralized Policy Agent Configuration

Text-based, needs no further explanation.

Figure 4–3 Process flow for Centralized Policy Agent Configuration (continued)

Text-based, no further explanation necessary.

Considering Assumptions, Dependencies, and Constraints

You must use the OpenSSO Enterprise administration console or the OpenSSO Enterprise command—line tools to create, delete, and manage the policy agent configurations.

Understanding Typical Business Use Cases

The following are typical use cases for using Policy Agents and the Client SDK to integrate OpenSSO Enterprise with applications in an existing deployment:

Using Non-Intrusive, Policy Agent-Based Approaches to Web Resources

The following are examples of capabilities that can be leveraged by using the Policy Agents to integrate OpenSSO Enterprise with other applications:

Pure J2EE applications

Pure J2EE applications are deployed as WARs installed on J2EE compliant application servers. The resources to be protected include servlets, JavaServer Pages and Enterprise JavaBeans.
Apache or Sun Web Server-based web applications

These applications can be HTML pages, multimedia content, and CGIs such as PHP, Perl, JSP, and servlets hosted on the web server.
.Net /IIS server-based web applications

These include .Net/ASP or ASPX applications such as Visual Basic and C#, HTML pages and content accessible via the HTTP protocol.
Enterprise applications

These include SAP, Siebel, Domino, PeopleSoft, and Portal middleware.
Proxied applications

This use case can include all web applications deployed with a reverse proxy server in front of it. No policy agents or added software are required be deployed on the application and its container. A proxy is installed separately from the application, and the policy agent installation also stays separate. Multiple applications can be proxied by the same proxy server, enabling a single agent to protect them all.

Leveraging Fat Clients, Custom Web Applications, and Enterprise JavaBeans

The following are examples of capabilities that can be leveraged by using the Client SDK to integrate OpenSSO Enterprise with other applications:

Java or C /C++

Applications can be enabled to directly invoke the Client SDK for authentication, authorization, and auditing services.
Password Replay

This use case is for legacy applications that require the user to submit credentials directly to the application before access to services is allowed.
Application-initiated Authentication

In this use case, the authentication authority is the application itself. Once the user is authenticated, the remaining security services such as single sign-on, policy evaluation, and identity federation are provided by OpenSSO Enterprise.

Complementing Policy Agent Functionality

In this use case, an OpenSSO Enterprise policy agent is deployed and the Client SDK is embedded in the application or its container. The following are ways in which this configuration helps to complement policy agent functionality:

Custom service-based access control is automatically in place.
Policy agents can handle only URL—based policy. The Client SDK can handle various non-URL based policies.
The Client SDK provides more finely-grained security control that is not possible with policy agents alone.

Enabling Identity Federation

Companies integrate applications with OpenSSO Enterprise to implement identity federation in various ways.

OpenSSO Enterprise passes attributes from an Identity Provider application to a Service Provider. In this use case, the Identity Provider passes user attribute value pairs to the Service Provider so the Service Provider can provide services to the user based on those attributes.
OpenSSO Enterprise receives Identity Provider-asserted attributes in a Service Provider application. In this use case the Service Provider verifies the authenticity of the attributes asserted by the Identity Provider. The Service Provider then updates its session with those attributes.
The OpenSSO Enterprise Fedlet quickly enables federation without having to install a full-featured OpenSSO Enterprise sever at the Service Provider. In this use case, the Service Provider can participate in Federation with an Identity Provider that does have the full-featured OpenSSO Enterprise server installed on it.

Enabling Web Services Security

Companies integrate applications with OpenSSO Enterprise to take advantage of the following OpenSSO Enterprise Web Services Security measures:

Protecting a web services provider endpoint
Protecting a web services client invocation

Enabling Identity Services

Applications integrated with OpenSSO Enterprise are able to consume simple OpenSSO Enterprise services in both the SOAP/WSDL style and the REST style. OpenSSO Enterprise may include one or more of the following:

Authentication
Authorization of an authenticated identity to access a resource
Retrieval of an authenticated identity's attributes
Logging

Coexisting with Non-Sun Deployments

Companies typically integrate OpenSSO Enterprise with non-Sun identity services for two purposes:

To maintain backward compatibility with legacy applications in an existing environment

In this use case, legacy non-Sun applications for authentication, authorization, and auditing have already been deployed and will continue to be used in the environment. OpenSSO Enterprise is used primarily to execute federation among both legacy and future applications. OpenSSO Enterprise may also be used for identity services when new applications are added to the environment.
To facilitate complete migration from the non-Sun identity services to OpenSSO Enterprise

In this use case, legacy non-Sun applications for authentication, authorization. and auditing have already been deployed. These applications must be maintained until OpenSSO Enterprise can be deployed and tested. Once OpenSSO Enterprise is successfully deployed, the legacy non-Sun identity services are phased out of the environment.

Setting Up and Configuring the Integrated Environment

Before you can integrate other applications with OpenSSO Enterprise, you must resolve the following issues:

Deployment Planning

The following steps form a very general and high-level guide to determine what approach is best for you.

Determine if an OpenSSO Enterprise Policy Agent is available for the container or application you want to use.
Determine if the proxy OpenSSO Enterprise Policy Agent is usable in front of the application.
Determine if the application or container plug-ins that externalizes security (independent of the application business logic) are available and pluggable. Consider using the Client SDK to implement these plug-ins. This is how an OpenSSO Enterprise policy agent typically starts out.
Determine if a signed and encrypted query, post, or XML API is applicable.
Determine if you need to embed the Client SDK in your application or container. The obvious example is when “no” is the answer in the all of the four previous steps. You may still need to use this approach if certain functionality is not supplied by an available policy agent. An example is when you must use fine-grained, application-specific policies.
Consider using Server SPIs to customize the OpenSSO Enterprise server behavior to your needs.

Required Hardware and Software

The following software components are required to integrate OpenSSO Enterprise with other applications:

Sun OpenSSO Enterprise 8.0
Sun OpenSSO Enterprise 8.0 Client SDK
Sun OpenSSO Enterprise Policy Agent 3.0

Some programming effort using the OpenSSO Enterprise Client SDK is required to implement the following business use cases:

Installing and configuring an OpenSSO Enterprise Policy Agent is required to implement the following business use cases:

In OpenSSO Enterprise Policy Agent 3.0 the Centralized Agent Configuration feature enables centralized Policy Agent management. In earlier versions, the Policy Agent configuration is local to the server being protected.

Downloading the Client SDK

Download the OpenSSO Enterprise Client SDK from the following URL:

https://opensso.dev.java.net/public/use/index.html

The OpenSSO Enterprise Client SDK is part of the opensso_enterprise_80.zip distribution, and is present in the samples/opensso-client.zip file within that distribution. See the README files inside the opensso-client.zip file for instructions on installing the OpenSSO Enterprise SDK. The OpenSSO Enterprise API Javadoc is available in the docs/opensso-public-javadocs.jar file.

Downloading the OpenSSO Enterprise Policy Agent 3.0

For download and installation information, go to the OpenSSO Enterprise Policy Agent 3.0 website at the following URL: .

You will also find other useful articles about Policy Agent troubleshooting.

The OpenSSO Enterprise command-line interface tool ssoadmin supports the following Policy Agent operations through it sub-commands:

Create a Policy Agent configuration
Delete a Policy Agent configuration
Update a Policy Agent configuration
List Policy Agent configurations
Display a Policy Agent configuration
Create a Policy Agent group
Delete a Policy Agent group
List agent groups
List Policy Agent group members
Add a Policy Agent to a group
Remove a Policy Agent from a group

The OpenSSO Enterprise administration console supports all of the above operations. The table below summarizes the compatibility between the various versions of OpenSSO Enterprise and the OpenSSO Enterprise Policy Agent.

Table 4–1 OpenSSO Enterprise Server Compatibility with OpenSSO Enterprise Policy Agents


OpenSSO Enterprise	Policy Agent
OpenSSO Enterprise 8.0 (OpenSSO v1)	Policy Agent 3.0, 2.2
Access Manager 7.0, 7.1	Policy Agent 3.0, 2.2
Access Manager 6.3	Policy Agent 2.2

Evaluating Benefits and Tradeoffs

The following lists may help you determine whether using the Client SDK or using a policy agent is suitable in your environment:

Benefits of Using the Client SDK

Using the Client SDK at the container or proxy server is a non-intrusive technique.
Using the proxy-based approach is the least intrusive of all options presented in this chapter. The proxy-based technique does not require interaction with the application container or machine at all. It also has the added advantage of proxying multiple applications with the same proxy server.

Tradeoffs Using the Client SDK

Embedding the Client SDK directly in a standalone application's business logic is an intrusive technique.
Embedding the Client SDK directly in a container-hosted application is an intrusive technique.

Benefits of Using a Policy Agent

The Centralized Policy Agent Configuration moves most of the Policy Agent configuration to the OpenSSO Enterprise data repository. Using the Centralized Policy Agent Configuration results in the following benefits:

Using Policy Agents is a less intrusive approach to application integration than embedding the OpenSSO Enterprise Client SDK in the application.
Using the proxy-based approach the least intrusive of all options presented in this chapter. The proxy-based approach does not require interaction with the application container or host machine at all. It also has the added advantage of proxying multiple applications with the same proxy server.
The Centralized Policy Agent Configuration supports all existing Policy Agent functionality including Policy Agent installation and uninstallation options. Using this feature allows separation between agent initialization data and agent configuration data.
An agent administrator can manage multiple Policy Agent configurations from one central location, and can use either the OpenSSO Enterprise administration console or the command-line interface to do this.
Any Policy Agent configuration changes are automatically conveyed to the affected agents, and the agents react to changes accordingly based on the nature of the updated properties. The administrator is not required to access the agent server to make this happen.
Most of the Policy Agent configuration properties are hot-swappable. This means that when any Policy Agent configuration properties are changed in the centralized agent configuration, the affected agent will use the changed property values without having to restart itself. The Policy Agent makes calls to the OpenSSO Enterprise attribute service periodically to retrieve its configuration data.
Centralized Policy Agent Configuration significantly reduces the time and resources spent on Policy Agent configuration management and Policy Agent patching.

Finding More Information

Policy Agents 3.0

http://wikis.sun.com/display/OpenSSO/PolicyAgents3
OpenSSO Enterprise Wiki Home

http://wikis.sun.com/display/OpenSSO
Download OpenSSO Software

https://opensso.dev.java.net/public/use/index.html
"Representational State Transfer" (REST)

By Roy Fielding, who introduced the concept in 2000

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm