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 by FileNet P8, and how support for additional standard profiles, as well as non-standard WS-Security compliant approaches, can 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.
The Web
Services Security Username Token Profile (available from http://docs.oasis-open.org)
specifies how user name and 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 can 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 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 user name and 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 Content Engine via the Enterprise Java™ Beans (EJB) transport.
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.
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.
The following steps occur in this graphic:
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 can use an HTTPS connection anyway to ensure privacy for information contained in the request and response bodies.)
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 log in 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.
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 Content Engine 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 Content Engine via the EJB transport.
See also Kerberos for Content Engine for more details on using Kerberos.
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 built into 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 these two token types, FileNet P8 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.
The following steps occur in this graphic:
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 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.