Sun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Application Server 9.0/Web Services

Chapter 1 Authentication Agents for Web Services

Sun Java™ System web services security providers are authentication agents integrated into a Java™ Platform, Enterprise Edition (Java EE) compatible web container. This chapter provides introductory material and background on these authentication agents. It includes the following sections:

Web Services

A web service is an application that exposes some type of functionality using a platform-independent interface. Enterprises use web services as a mechanism for allowing their applications to cross network boundaries and communicate with those of their partners, customers and suppliers. Web services are accessed by sending a request to one of the service's defined endpoints. The following open technologies are used to allow this access.

Web Services Definition Language: Web Services Definition Language (WSDL) is a variant of the eXtensible Markup Language (XML) that is used to describe the public interfaces for a web service. Specifically, this includes the protocol bindings, service endpoints (identified by URLs), and message formats required to interact with it. Once defined, a web service's WSDL description file is published to a worldwide directory of services allowing it to be accessed over the Internet. The directory might use Universal Description, Discovery, and Integration (UDDI) although alternate forms are available.
eXtensible Markup Language: Data exchanged with a web service (requests sent to it and responses received from it) is formatted using XML.
SOAP: The XML requests and responses generally conform to the SOAP messaging standard.
Hypertext Transfer Protocol (HTTP): SOAP messages are transported between applications using HTTP although File Transfer Protocol (FTP), Simple Mail Transfer Protocol (SMTP) and Extensible Messaging and Presence Protocol (XMPP) can also be used.

The built-in openness of these technologies unfortunately though creates security risks. The following security requirements have been identified and must be supported to insure that the communications between a web service provider (WSP) and a web service client (WSC) are not compromised.

Data integrity and confidentiality during transport
Authentication of the sending entity
Message uniqueness

Securing web services communications was initially addressed on the transport level, relying on securing the HTTP transmissions themselves using Secure Sockets Layer (SSL). This is not adequate though when access to an application is requested through an intermediary. The solution to this is to encrypt the entire request using message level security before it is sent. In message level security, security information is contained within the SOAP message or attachment, making it independent of the transport level security. The request may then securely pass through multiple intermediaries before reaching its intended receiver for decryption. The following illustration depicts message level security.

Illustration of security context in message level
security

Java Authentication Service Provider Interface for Containers

There are a number of organizations that work on web services security specifications, guidelines, and tools including the World Wide Web Consortium (W3C), the Organization for Advancement of Structured Information Standards (OASIS), the Liberty Alliance Project and the Java Community Process (JCP). The JCP primarily guides the development and approval of Java technical specifications, one of which is the Java Specification Request (JSR) 196. JSR 196 is a draft of the Java Authentication Service Provider Interface for Containers. It defines a standard service provider interface (SPI) with which a message level authentication agent can be developed for Java EE containers on either the client side or the server side. 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.

Note –

The JSR 196 draft specifications are available at http://www.jcp.org/en/jsr/detail?id=196.

A typical interaction between a WSC and a WSP begins with a request from the WSC. The container to which the WSP is deployed receives the request and dispatches it to the correct web service 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 illustrates this process in more detail with the steps provided below it. This process 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 authentication 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 authentication 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 authentication 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 authentication 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.

The JSR–196 SPI is structured so that the security processes can be delegated to an authentication agent at any of four interaction points in this scenario. The four points represent the methods of the corresponding ClientAuthModule and ServerAuthModule interfaces defined by the SPI and include:

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

Thus, when a WSC and WSP are both deployed in a Java EE web container protected by a JSR–196 authentication agent, the initial request from the WSC is intercepted by the authentication agent on the client side. The client side agent queries a trusted authority (for example, the Discovery Service in Access Manager) to retrieve the necessary authorization credentials and secure them to the request. The request is then passed to the WSP. The authentication agent on the provider side receives the request to validate the authorization credentials. If validation is successful, the request is exposed to the web service and a response is created using the sender's credentials and the application specific request. The response is then intercepted by the authentication agent on the provider side to secure it and return it to the WSC. Upon receiving the response, the authentication agent on the client side validates it and dispatches it to the client application. This is illustrated in the following graphic.

The four points in the interaction between a
web service client and web service provider where security processes
can be added.

Sun Java System Access Manager Policy Agent 2.2 for Sun Java System Application Server 9.0 / Web Services

In general, securing web services involves establishing trust between a WSC and a WSP. For identity-based web services specifically (for example, a calendar service), the WSP would have to trust the WSC to have authenticated the user, or the WSC would have to include the user's credentials as part of the web service request. The distinguishing factor is that identity-based web services authenticate both the WSC and the user's identity. (The user must be authenticated so that the WSC can send the user's token to the WSP in a SOAP security header.)

The Sun Java System Access Manager Policy Agent 2.2 for Sun Java System Application Server 9.0 / Web Services plugs into Application Server Platform Edition 9.0, provides message level security, and supports both Liberty Alliance Project token profiles as well as Web Services-Interoperability Basic Security Profiles (WS-I BSP). (A profile defines the HTTP exchanges required to transfer XML requests and responses between web service clients and providers.)

Note –

More information on Application Server Platform Edition 9.0 can be found in the collection of documentation provided for the product located at http://docs.sun.com/coll/1343.3.

This release of the agent uses an instance of Access Manager for all authentication decisions. Web services requests and responses are passed to Access Manager authentication modules using standard Java representations based on the transmission protocol. Currently, the Policy Agent 2.2 for Sun Java System Application Server 9.0 / Web Services provides the following agents:

HTTP Authentication Agent

The HTTP authentication agent protects the endpoints of a web service that uses HTTP for communication. After the HTTP authentication agent is deployed in an instance of Application Server on the WSP side, all HTTP requests for access to web services protected by the agent are redirected to the login and authentication URLs defined in the Access Manager AMConfig.properties file on the WSC side. AMConfig.properties is located in javaee.home/domains/domain_name/config when the Java Platform, Enterprise Edition (Java EE) 5 SDK is installed and in javaee.home/addons/amserver when the Java EE 5 Tools Bundle is installed. The configurable properties are:

com.sun.identity.loginurl=amserver_protocol://amserver_host:amserver_port/amserver/UI/Login
com.sun.identity.liberty.authnsvc.url=amserver_protocol://amserver_host:amserver_port/amserver/Liberty/authnsvc

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.

When the WSC makes a request to access a web application protected by an HTTP authentication agent (1 in the illustration below), the agent intercepts the request and redirects it (via the browser) to Access Manager 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).

Note –

For this release, the HTTP authentication agent is used primarily for bootstrapping. Future releases will contain information on how to protect web applications.

The following figure illustrates the interactions described.

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

Note –

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

SOAP Authentication Agent

The SOAP authentication agent secures SOAP messages between a WSC and a WSP. The agent can be configured for use as an authentication provider on either the WSC server or the WSP server. This initial release encapsulates the Liberty Identity Web Services Framework (Liberty ID-WSF) SOAP Binding Specification as implemented by Access Manager and supports the following:

Note –

The configuration process for the SOAP authentication agent is described in Installing the Policy Agent 2.2 for Sun Java System Application Server 9.0 / Web Services.

Supported Liberty Alliance Project Security Tokens

In a scenario where security is enabled using Liberty Alliance Project tokens, the HTTP client requests (via the WSC) access to a service. The HTTP authentication agent redirects the request to the Access Manager 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 authentication 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 authentication 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 authentication agent on the WSP side, back to the WSC. The SOAP authentication 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 authentication 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.

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 HTTP client requests (via the WSC) access to a service. The SOAP authentication agent redirects the request to the Access Manager 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 authentication 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.

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.