Sun OpenSSO Enterprise 8.0 Developer's Guide

Security Agents

There are two kinds of security agents developed for web services security. One protects the WSC and the other protects the WSP. The WSC which makes the web service call provides support for securing the outgoing communications and validating the incoming responses from a WSP. The WSP which provides a service from a WSC call provides support for validating the incoming request and securing the outgoing responses. These agents may establish the authenticated identities used by the containers allowing:

A server side agent to verify security tokens or signatures on incoming requests and extract principal data or assertions before adding them to the client security context.
A client side agent to add security tokens to outgoing requests, sign messages, and interact with the trusted authority to locate targeted web service providers.

A typical interaction between a WSC and a WSP begins with a request from the WSC. The container on which the WSP is deployed receives the request and dispatches it to perform the requested operation. When the web service completes the operation, it creates a response that is returned back to the client. The following illustration and procedure illustrates a scenario when both client and service web containers employ the Java Authentication SPI.

A typical interaction between a web services
client and a web services provider

The client browser's attempt to invoke a web service is intercepted by the client's web container.
The deployed security agent on the client's web container is invoked to secure the request (based on the security policy of the web service being invoked).
The client's web container sends the secured request message to the web service.
The web service's web container receives the secured request message and it's deployed security agent is invoked to validate the request and obtain the identity of the caller.
Assuming successful authentication, the web service's web container invokes the requested web service.
This action (the invocation of the web service) is returned to the web service's web container as a response.
The deployed security agent on the web service's web container is invoked to secure the response message.
The web service's web container sends the secured response message to the client.
The deployed security agent on the client's web container is invoked to validate the secured response message.
The invocation of the web service is returned to the client browser.

Security processes can be delegated to a security agent at any of the following interaction points.

Securing a request on the client side
Validating a request on the provider side
Securing a response on the provider side
Validating a response on the client side

This security agent uses an instance of OpenSSO Enterprise for all authentication decisions. Web services requests and responses are passed to the authentication modules using standard Java representations based on the transmission protocol. Currently, the following security agents are provided.

WSC Security Agents

The WSC security agent protects the endpoints of a web service that uses HTTP for communication. After the WSC security agent is deployed in a web container on the WSP side, all HTTP requests for access to the web services protected by the agent are redirected to the login and authentication URLs defined in the OpenSSO Enterprise configuration data store on the WSC side.

Note –

The available WSC security agent was developed using the Java Specification Request (JSR) 196. JSR 196 is the Java Authentication Service Provider Interface for Containers. It defines a standard service provider interface (SPI) with which a security agent can be developed to police Java EE containers on either the client side or the server side. These agents establish the authenticated identities used by the containers. The JSR 196 specifications are available at http://www.jcp.org/en/jsr/detail?id=196.

When the WSC makes a request to access a web application (1 in the illustration below), the agent intercepts the request and redirects it (via the browser) to OpenSSO Enterprise for authentication (2). Upon successful authentication, a response is returned to the application, carrying a token as part of the Java EE Subject (3). This token is used to bootstrap the appropriate Liberty ID-WSF security profile. If the response is successfully authenticated, the request is granted (3).

HTTP security agent protecting HTTP requests
to, and responses from, service providers

Note –

The functionality of the HTTP security agent is similar in to that of the Java EE policy agents when used in SSO ONLY mode. This is a non restrictive mode that uses only the OpenSSO Enterprise Authentication Service to authenticate users attempting access. For more information on Java EE policy agents, see the Sun Java System Access Manager Policy Agent 2.2 User’s Guide.

Note –

Application Server 9 has the ability to configure only one HTTP agent per instance. Therefore, all authentication requests for all web applications hosted in the container will be forwarded to the one configured agent.

WSP Security Agent

The WSP which provides a service based on calls from a WSC provides support for validating incoming requests and securing outgoing responses. This agent encapsulates the Web Services-Interoperability Basic Security Profile (WS-I BSP) tokens as well as the Liberty Identity Web Services Framework (Liberty ID-WSF) SOAP Binding Specification tokens:

Supported Web Services-Interoperability Basic Security Profile Security Tokens

In a scenario where security is enabled using Web Services-Interoperability Basic Security Profile (WS-I BSP) tokens, the client requests access to a service. The configured security agent reads the configuration from the OpenSSO Enterprise configuration data store and redirects the request to the OpenSSO Enterprise Authentication Service for authentication and to determine the security mechanism registered by the WSP and obtain the expected security tokens. After a successful authentication, the WSC provides a SOAP body while the SOAP security agent on the WSC side inserts the security header and a token. The message is then signed before the request is sent to the WSP.

When received by the security agent on the WSP side, the signature and security token in the SOAP request are verified before forwarding the request on to the WSP itself. The WSP then processes it and returns a response, signed by the security agent on the WSP side, back to the WSC. The SOAP security agent on the WSC side then verifies the signature before forwarding the response on to the WSC. The following diagram illustrates the interactions as described.

Illustration of interactions between WSC and
WSP with deployed SOAP Provider agents for WS-I BSP security tokens

The following WS-I BSP security tokens are supported in this release.

User Name: A secure web service requires a user name, password and, optionally, a signed the request. The web service consumer supplies a username token as the means for identifying the requester and a password, shared secret, or password equivalent to authenticate the identity to the web service provider.
X.509: A secure web service uses a PKI (public key infrastructure) in which the web service consumer supplies a public key as the means for identifying the requester and accomplishing authentication with to the web service provider.
SAML-Holder-Of-Key: A secure web service uses the SAML holder-of-key confirmation method. The web service consumer supplies a SAML assertion with public key information as the means for authenticating the requester to the web service provider. A second signature binds the assertion to the SOAP payload.
SAML-SenderVouches: A secure web service uses the SAML sender-vouches confirmation method. The web service consumer adds a SAML assertion and a digital signature to a SOAP header. A sender certificate or public key is also provided with the signature.

Supported Liberty Alliance Project Security Tokens

In a scenario where security is enabled using Liberty Alliance Project tokens, the client requests (via the WSC) access to a service. The security agent redirects the request to the OpenSSO Enterprise Authentication Service for authentication and to determine the security mechanism registered by the WSP and obtain the security tokens expected. After a successful authentication, the WSC provides a SOAP body while the SOAP security agent on the WSC side inserts the security header and a token. The message is then signed before the request is sent to the WSP.

When received by the SOAP security agent on the WSP side, the signature and security token in the SOAP request are verified before forwarding the request on to the WSP itself. The WSP then processes it and returns a response, signed by the SOAP security agent on the WSP side, back to the WSC. The SOAP security agent on the WSC side then verifies the signature before forwarding the response on to the WSC. The following diagram illustrates the interactions as described.

SOAP security agent protecting communications
between clients and service providers

The following Liberty Alliance Project security tokens are supported in this release:

X.509: A secure web service uses a PKI (public key infrastructure) in which the web service consumer supplies a public key as the means for identifying the requester and accomplishing authentication with the web service provider. Authentication with the web service provider using processing rules defined by the Liberty Alliance Project.
BearerToken: A secure web service uses the Security Assertion Markup Language (SAML) SAML Bearer token confirmation method. The web service consumer supplies a SAML assertion with public key information as the means for authenticating the requester to the web service provider. A second signature binds the assertion to the SOAP message This is accomplished using processing rules defined by the Liberty Alliance Project
SAMLToken: A secure web service uses the SAML holder-of-key confirmation method. The web service consumer adds a SAML assertion and a digital signature to a SOAP header. A sender certificate or public key is also provided with the signature. This is accomplished using processing rules defined by the Liberty Alliance Project.