test

Sun Java System Access Manager 7.1 Federation and SAML Administration Guide

Chapter 6 Authentication Web Service

Sun Java™ System Access Manager contains the Authentication Web Service. It enables web service consumers and Liberty-enabled user agents to authenticate with identity providers using SOAP messages. This chapter covers the following topics:

Authentication Web Service Overview

The SOAP specifications define an XML-based messaging paradigm, but do not specify any particular security mechanisms. Particularly, they do not describe user authentication using SOAP messages. To rectify this, the Authentication Web Service was implemented based on the Liberty ID-WSF Authentication Service and Single Sign-On Service Specification. The specification defines a protocol that adds the Simple Authentication and Security Layer (SASL) authentication functionality to the SOAP binding described in the Liberty ID-WSF SOAP Binding Specification and, Chapter 9, SOAP Binding Service in this guide. The Authentication Web Service is for provider-to-provider authentication.

Note –

The specification also contains an XML schema that defines the authentication protocol. More information can be found in Schema Files and Service Definition Documents.

This overview contains the following sections:

XML Service File

The Authentication Web Service is configured using the XML service file amAuthnSvc.xml. This file defines the attribute for the Authentication Web Service which can be managed through the Access Manager console or the XML file.

Note –

For information about service files, see the Sun Java System Access Manager 7.1 Administration Guide.

Authentication Web Service APIs

The Access Manager Authentication Web Service includes the following Java programming packages:

The first package is a client API for external Java applications to send SASL requests and receive SASL responses. The second package defines an interface to handle different SASL mechanisms. The final package contains classes that represent the SASL request and response. Together, the packages are used to initiate the authentication process and communicate authentication credentials to the Authentication Web Service. For more information, see the Authentication Web Service API.

Which Authentication Service to Use?

The Liberty-based Authentication Web Service is not to be confused with the proprietary Authentication Service discussed in the Sun Java System Access Manager 7.1 Administration Guide. Architecturally, the Authentication Web Service sits on top of the Access Manager Authentication Service and the Liberty Alliance Project framework. You might use the Authentication Web Service if you are a service provider and want to use a standards-based mechanism to authenticate users.

Following are two use cases where the Authentication Web Service is preferable to the Access Manager Authentication Service:

In addition to providing an authentication service to verify credentials (for example, user ID and password), the Authentication Web Service provides the web services consumer (WSC) with bootstrap information that contains the endpoint and credentials needed to access the Discovery Service (as discussed in Chapter 8, Discovery Service). The WSC can ignore the bootstrap or use it to access other web services, such as the authenticated user's personal profile or calendar.

Note –

An authenticated enterprise might also use the bootstrap information to access a partner in a business-to-business environment.

Following is an example that shows how the Authentication Web Service interacts with the Access Manager Authentication Service. It assumes the following separate entities:

The WSC delegates all authentication to the identity provider and prefers PLAIN authentication which accepts a user identifier and password.

  1. The user attempts access to a service provider (not necessarily hosted by Access Manager).

  2. When the service provider finds that the user is not authenticated, it invokes the identity provider's Authentication Web Service by sending it a SOAP request.

  3. After inspecting its configuration, the Authentication Web Service sends back a response indicating that it supports Certificate and PLAIN authentication.

  4. The service provider decides on PLAIN authentication and prompts the user for an identifier and password.

  5. Interactions based on the standard PLAIN authentication mapping ensues between the service provider and identity provider (hosted on Access Manager) using the Authentication Web Service.

    1. The service provider receives the user identifier and password and sends it to the identity provider.

    2. The identity provider passes the credentials to the locally hosted LDAP Authentication module using the proprietary Access Manager Authentication Service's Java API.

    3. The LDAP Authentication module verifies the credentials.

    4. The Authentication Web Service is notified of the verification and sends a response to the service provider indicating successful authentication. If configured to do so, it also includes bootstrap information formatted using XML and containing the Discovery Service endpoint and a token to invoke it.

  6. The service provider parses the response, verifies that it is a successful authentication, and provides the service to the user.

At some point the service provider might need to access the user's personal profile. To do this, it will use the bootstrap information received during this process to contact the Discovery Service and find where the profile is stored. The Discovery Service returns a resource offering (containing a token and the location of an endpoint), and the service provider uses that to invoke the Liberty Personal Profile Service.

Authentication Web Service Process

The exchange of authentication information between a web service consumer (WSC) and the web service provider (WSP) is accomplished using SOAP-bound messages. The messages are a series of client requests and server responses specific to the defined SASL mechanism (or mode of authentication). The authentication exchange can involve an arbitrary number of round trips, dictated by the particular SASL mechanism employed. The WSC might have knowledge of the supported SASL mechanisms, or it might send the server its own list of mechanisms and allow the server to choose one. The list of supported mechanisms can be found at http://www.iana.org/assignments/sasl-mechanisms.

After receiving a request for authentication (or any response from the WSC), the WSP may issue additional challenges or indicate authentication failure or success. The sequence between the WSC and the Authentication Web Service (a WSP) is as follows.

  1. The authentication exchange begins when a WSC sends an SASL authentication request to the Authentication Web Service on behalf of a principal.

    The request message contains an identifier for the principal and indicates one or more SASL mechanisms from which the service can choose.

  2. The Authentication Web Service responds by asserting the method to use and, if applicable, initiating a challenge.

    If the Authentication Web Service does not support any of the cited methods, it responds by aborting the exchange.

  3. The WSC responds with the necessary credentials for the chosen method of authentication.

  4. The Authentication Web Service replies by approving or denying the authentication.

    If approved, the response includes the credentials the WSC needs to invoke other web services, such as the Discovery Service.

Authentication Web Service Attribute

The Authentication Web Service attribute is a global attribute. The value of this attribute is carried across the Access Manager configuration and inherited by every organization.

Note –

For information about the types of attributes used in Access Manager, see the Sun Java System Access Manager 7.1 Technical Overview.

The attribute for the Authentication Web Service is defined in the amAuthnSvc.xml service file and is called the Mechanism Handlers List.

Mechanism Handlers List

The Mechanism Handler List attribute stores information about the SASL mechanisms that are supported by the Authentication Web Service.

key Parameter

The required key defines the SASL mechanism supported by the Authentication Web Service.

class Parameter

The required class specifies the name of the implemented class for the SASL mechanism. Two authentication mechanisms are supported by the following default implementations:

Table 6–1 Default Implementations for Authentication Mechanism

Class 

Description 

com.sun.identity.liberty.ws.authnsvc.mechanism.PlainMechanismHandler

This class is the default implementation for the PLAIN authentication mechanism. It maps user identifiers and passwords in the PLAIN mechanism to the user identifiers and passwords in the LDAP authentication module under the root organization. 

com.sun.identity.liberty.ws.authnsvc.mechanism.CramMD5MechanismHandler

This class is the default implementation for the CRAM-MD5 authentication mechanism. 

Note –

The Authentication Web Service layer provides an interface that must be implemented for each SASL mechanism to process the requested message and return a response. For more information, see com.sun.identity.liberty.ws.authnsvc.mechanism Package.

Authentication Web Service API

The Authentication Web Service provides programmatic interfaces to allow clients to interact with it. The following sections provide short descriptions of these packages. For more detailed information, see the Java API Reference in /AccessManager-base/SUNWam/docs or on docs.sun.com. The authentication-related packages include:

com.sun.identity.liberty.ws.authnsvc Package

This package provides web service clients with a method to request authentication credentials from the Authentication Web Service and receive responses back from it using the Simple Authentication and Security Layer (SASL).

com.sun.identity.liberty.ws.authnsvc.mechanism Package

This package provides an interface that must be implemented for each different SASL mechanism to enable authentication using them. Each SASL mechanism will correspond to one implementation that will process incoming SASL requests and generate outgoing SASL responses.

com.sun.identity.liberty.ws.authnsvc.protocol Package

This package provides classes that correspond to the request and response elements defined in the Liberty XSD schema that accompanies the Liberty ID-WSF Authentication Service Specification. More information about the XSD schemas can be found in Schema Files and Service Definition Documents.

Access the Authentication Web Service

The URL to gain access to the Authentication Web Service is:


http://SERVER_HOST:SERVER_PORT/SERVER_DEPLOY_URI/Liberty/authnsvc

This URL is normally used by the Access Manager client API to access the service. For example, the Access Manager public client, com.sun.identity.liberty.ws.authnsvc.AuthnSvcClient uses this URL to authenticate principals with Access Manager.

Authentication Web Service Sample

A sample authentication client is included with Access Manager. It is located in the /AccessManager-base/SUNWam/samples/phase2/authnsvc directory. The client uses the PLAIN SASL authentication mechanism. It first authenticates against the Authentication Web Service, then extracts a resource offering to bootstrap the Discovery Service. It looks for a SAML Bearer token credential, issues a discovery query request with SAML assertion included, and receives a response.

Note –

This sample can be used by a Liberty User Agent Device WSC.