Web-Services-based client authentication via Ws-Security

The WS-Security overview describes the WS-Security standard and how it relates to FileNet P8 web services. This topic discusses how two specific WS-Security profiles, the Username Token profile and the Kerberos profile, are supported out-of-the-box by FileNet P8, and how support for additional standard profiles, as well as non-standard WS-Security compliant approaches, may be integrated with FileNet P8 web services, using the FileNet P8 Web Service Extensible Authentication Framework.

Clients of a web service must produce WS-Security compliant headers to use any of the FileNet P8 web services. Most web service-based applications are created using a toolkit, such as Microsoft's Visual Studio, which handles the creation of WS-Security compliant headers.

Username token credentials

The Web Services Security Username Token Profile (available from http://docs.oasis-open.org) specifies how username/password-based credentials can be passed in a WS-Security header. All web service clients that adhere to this profile should be able to interact with any web service that implements the profile. The XML <wsse:UsernameToken> and <wsse:PasswordToken> elements are defined, along with rules for how these fields must be used.

When Username tokens are sent in a WS-Security header, a secure, private channel, such as an HTTPS connection, must be used between the client and the server to prevent compromising the client's password. Two types of passwords are defined by this standard: a text password and a password digest. FileNet P8 supports only the text password option.

There are two optional elements that may be included in a Username token as counter measures against replay attacks: the nonce and creation timestamp fields.

Use of both of these fields is recommended, but not required, for all web service implementations.

An example of a WS-Security header containing a Username token is shown below (some of the namespace values have been truncated, for the sake of brevity):

<wsse:Security soap:mustUnderstand="1">
  <wsu:Timestamp wsu:Id="Timestamp-3290b465-8a4a-4e34-b5da-1e35d80d613b">
    <wsu:Created>2005-11-17T19:24:15Z</wsu:Created>
    <wsu:Expires>2005-11-17T19:29:15Z</wsu:Expires>
  </wsu:Timestamp>
  <wsse:UsernameToken xmlns:wsu="…" Id="SecurityToken-84353116-ed06-4a1a-b896-19337481c488">
    <wsse:Username> MyUsername </wsse:Username>
    <wsse:Password Type="…#PasswordText"> MyPassword </wsse:Password>
    <wsse:Nonce>QkzWRIL2COP9D4ELX4LyZQ==</wsse:Nonce>
    <wsu:Created>2005-11-17T19:24:15Z</wsu:Created>
  </wsse:UsernameToken>
</wsse:Security>

When a web service request containing a Username token arrives at a Content Engine (CE) web service, the web service listener extracts the credentials from the WS-Security header, and uses them to perform a Java™ Authentication and Authorization Service (JAAS) login using an application-server-specific username/password Login Module. Once the JAAS login has successfully completed, the FileNet P8 web service listener is now in possession of a JAAS Subject, and can pass the call along to CE via the Enterprise Java™ Beans (EJB) transport.

Kerberos Credentials

The Web Services Security Kerberos Token Profile (available from http://www.oasis-open.org) specifies how Kerberos-based credentials can be passed in a WS-Security header.

Kerberos overview

In a Kerberos environment, clients obtain "tickets" that grant them access to interact with a particular server for a particular period of time. Servers are able to verify the validity of these tickets and of the user's identity. Symmetric encryption is used to secure the tickets and keys that are exchanged in a Kerberos environment.

A Kerberos environment requires the presence of one or more Kerberos Key Distribution Centers (KDCs). A KDC generates the encryption keys and tickets that are used in the environment. The next graphic illustrates the exchanges that occur in a typical Windows Kerberos-based client/server interaction (a UNIX® Kerberos interaction would be conceptually identical):

Kerberos KDC generates encryption keys and tickets that are passed to the Web services listener.

Kerberos KDC generates encryption keys and tickets that are passed to the Web services listener.

The following steps occur in this graphic:

  1. For authentication purposes, the client logs in to the Windows domain. The operating system collects the user's name and password and sends them to a KDC.
  2. The KDC works with a directory service to validate the user's credentials and returns a ticket-granting ticket (TGT) to the caller.
  3. Because the client wishes to access a particular server, a ticket-granting exchange must occur. The client sends a second request to the KDC, specifying the service that it wishes to access. (Note that if the client had previously been granted a service ticket and it has not yet expired, then steps 3 and 4 would be skipped).
  4. The KDC issues a service ticket, which grants the caller access to that service.
  5. The client sends its request with the service ticket encoded in a WS-Security Kerberos token to the server.
  6. The web service listener on the Content Engine server performs a JAAS login using credentials supplied in the incoming WS-Security header.
  7. The JAAS LoginModule validates the client's ticket. No roundtrip to the KDC is necessary. The server is able to use its own key (obtained from the KDC at startup time) to validate service tickets. The LoginModule produces a valid JAAS subject, based on the successful validation of the ticket. This JAAS subject is returned to the Content Engine web service listener.
  8. The Content Engine web service listener passes the call along (with valid JAAS subject) to the Content Engine EJB layer.

When Kerberos tokens are sent in a WS-Security header, a secure, private channel, such as an HTTPS (SSL) connection, is not required between the client and the server, as the tickets sent in a Kerberos request are already encrypted. (Customers may wish to use an HTTPS connection anyway to ensure privacy for information contained in the request and response bodies.)

Microsoft's use of Kerberos

Starting with Windows 2000, Microsoft embraced the Kerberos standard, and based the Windows authentication process on it. A Windows domain controller acts as a Kerberos KDC, and a Windows domain is equivalent to a Kerberos realm. Microsoft's use of Kerberos to authenticate Windows clients improved Windows scalability, and allowed interoperability with other non-Windows clients.

However, Microsoft's Kerberos implementation is not entirely compatible with the MIT implementations. Microsoft has made minor changes to the protocol that have introduced compatibility issues. With some work and some caveats, however, Windows and UNIX Kerberos clients can be made to interact.

Kerberos forms the basis for the "Windows Integrated Logon" capability that allows a Windows client to logon to the network and access network resources across the Windows domain (and in some cases, in other Windows domains).

Microsoft provides a web services development toolkit called Web Services Extensions (WSE) for creating web service-enabled client and server applications. WSE supports the use of Kerberos credentials, obtained from the client's environment, to generate WS-Security-compliant Kerberos tickets. FileNet P8 supports the use of these tickets in FileNet P8 web services, allowing Windows clients who have logged onto the domain to access FileNet P8 web services without providing any additional credentials.

Through use of Kerberos tokens, web service client applications can be developed allowing single sign-on with FileNet P8 web services in a Windows Integrated Logon environment.

Sample Kerberos token

Kerberos tokens are encoded in a WS-Security header using the standard <wsse:BinarySecurityToken> element. The Kerberos Token Profile defines how each of the attributes within this token must be set when sending Kerberos tokens. An example of a WS-Security header containing a Kerberos token is shown below (some of the namespace values have been truncated):

<wsse:Security soap:mustUnderstand="1">
  <wsu:Timestamp wsu:Id="Timestamp-a475236f-c2c8-4c37-a280-f6ae043b09dd">
    <wsu:Created>2005-04-09T00:17:53Z</wsu:Created>
    <wsu:Expires>2005-04-09T00:22:53Z</wsu:Expires>
  </wsu:Timestamp>
  <wsse:BinarySecurityToken
    ValueType ="wsse.Kerberosv5ST"
    EncodingType="wsse.Base64Binary"
    xmlns:wsu="http://.../oasis-200401-wss-wssecurity-utility-1.0.xsd"
    wsu:Id="SecurityToken-3b4344fc-374f-4e71-9d1c-e6a356a62f6b">YYID ... pPZt
   </wsse:BinarySecurityToken>
</wsse:Security>

(For information on the ValueType and EncodingType values, see the WS-Security specification.)

When a web service request containing a Kerberos token arrives at a FileNet P8 4.0 CE web service, the web service listener extracts the token from the WS-Security header, and uses it to perform a JAAS login using a FileNet-provided, application server specific Kerberos Login Module. Once the JAAS login has completed successfully, the FileNet P8 web service listener is now in possession of a JAAS Subject, and can pass the call along to CE via the EJB transport.

See also Kerberos for Content Engine for more details on using Kerberos.

Web Service extensible authentication framework

The previous two sections discussed how the standard Username and Kerberos token profiles can be used to authenticate against FileNet P8 web services. These are the only two credentials types supported out-of-the-box in FileNet P8 for use over the web services transport.

For clients that must use the web service transport but cannot make use of one of the two out-of-the-box token types, FileNet has provided a Web Services Extensible Authentication Framework (WS-EAF). This framework consists simply of a set of conventions for writing a JAAS Login Module that is able to interact with the FileNet P8 Content Engine web service listener to obtain the credentials that are present in the WS-Security header of an incoming request packet. The next figure illustrates this interaction:

Web Services Extensible Authentication Framework.

Web Services Extensible Authentication Framework.

The following steps occur in this graphic:

  1. A Content Engine web service client sends a request containing a custom set of credentials packaged in a WS-Security header.
  2. The request arrives at the CE web service listener. The web service listener extracts the WS-Security headers and examines them. It sees that they do not contain one of the out-of-the-box FileNet P8 credential types, so it invokes the FileNet P8 WS-EAF authentication mechanism. A JAAS CallbackHandler is created and seeded with the contents of the WS-Security header.
  3. A JAAS login is performed, specifying the FileNetP8Engine JAAS configuration and the CallbackHandler created in the previous step.
  4. The standard JAAS runtime looks up the login modules that are listed in the JAAS configuration file for the FileNetP8Engine stanza and invokes each of the listed Login Modules, passing in the CallbackHandler as a parameter.
  5. The custom WS-EAF JAAS Login Module instantiates one or more standard JAAS callbacks and passes these callbacks to the CallbackHandler's handle() method.
  6. For each callback that the client has requested, the Content Engine web service CallbackHandler supplies the callback with requested XML fragments from the incoming WS-Security header, such that they can be retrieved by the custom WS-EAF JAAS Login Module.
  7. The Login Module is now in possession of the WS-Security header information, and is able to use this information to perform its proprietary authentication process. If the authentication is successful, then a JAAS Subject is populated and returned.
  8. The Content Engine web service listener now has a valid JAAS Subject, and can call the Content Engine web service to handle the request, via the Content Engine EJB.

SAML credentials

The Security Assertion Markup Language (SAML) is a web services specification that defines how to encode security assertions in XML. FileNet P8 does not provide any explicit support for SAML tokens. However, the Web Services Extensible Authentication Framework defined in the previous topic can be used to build support for authenticating via SAML-based credentials within FileNet P8 applications.

Java-based clients over the web service transport

Java clients that use the web service transport are able to use only Username tokens. Neither Kerberos nor Web Service Extensible Authentication Framework support is available to Java-based clients over the web service transport.