Writing your own Simple Object Access Protocol (SOAP) message header handler may be necessary in some instances....
In this tutorial, I use a security header block to give a high-level view of the necessary changes when writing a SOAP message handler.
Getting into the pipeline
First you must modify the pipeline's eXtensible Markup Language (XML) configuration file for CICS to invoke the message handler. Listed below is CICS' sample Web service provider pipeline with a couple of highlighted alterations.
Click to enlarge.
The tag signals the beginning of the header processor definition, which is followed by the program name. Following the name space definition is the tag, in green, that tells CICS the type of header block the handler processes. This will make more sense later when we see an example of the input message.
The tag controls when CICS calls the handler. A value of "false" or "0" tells CICS to call the handler if the incoming message contains a "Security" header block. CICS will call the message hander for every incoming request if the tag is set to "True" or "1."
The tag terminates the definition for header program SECHEADR. Other processors may follow up until the tag.
Example SOAP request header block
The message handler has a couple of options for accessing the inbound message. Container DFHRESPONSE holds the entire message. DFHHEADER contains the header block pertinent to header processor CICS called.
Below is a sample header block for Security. I elided the name space URL's to save room.
Click to enlarge.
This is where we get to the hard part. As you can tell from the above example, XML in general and SOAP in particular are very verbose. Text-based messages containing self-defining fields are fine for passing information between disparate platforms. However, they play into one of the mainframe's weaknesses, string processing. Handling long messages in Assembler is relatively fast and cheap, but difficult. Other languages, such as PL/1, can parse text deftly, but with the performance penalty inherent in all higher level languages. The good news is that IBM may introduce an XML specialty engine -- although we'll just have to wait for CICS to support it.
As you've probably noticed, each SOAP tag begins with a less than sign ("<"), followed by a label. Following them are attributes consisting of name-value pairs that mean something to the process parsing the message. The tag ends with a greater than sign (">"). Following the starting tag is the content the tag describes. The end of the content is marked by a lesser than sign followed by a slash ("
SOAP is hierarchical, as tags are nested inside of each other. In fact, some tags are only valid nested in other tags or invalid if they appear in the wrong part of a message.
The catch to processing any header is not to be too specific or too vague. Looking for too specific of a string or, worse, assuming a given value, will always be at a certain offset and will likely break the header processing program any time the environment changes. On the other hand, too vague of a search may miss or misinterpret part of the message. This type of processing runs the risk of producing errors that are hard to debug.
I've highlighted a couple of strings in the above example. The first highlight shows the beginning of the header block CICS fished out of the message into container DFHHEADER. Note that the string "Security" matches the localname attribute in the pipeline configuration file.
Way down deep into the header I highlighted the user ID and password. Don't be fooled by the short tag attributes. I substituted three periods for some very long URLs that describe how to handle the credentials. The long attributes would be funny if it weren't someone's job to wade through the message to find the needed information.
Processing the header block for user credentials
This brings us to my ignorant-of-details, crossed-fingers, hack-at-it-until-it-works algorithm.
- Look for "
- Scan for "
- Look for "" to find the end of the user ID element. With the beginning and ending of the content I can calculate the length of the user ID and copy it into working storage.
- Next, look for "
- Skip all the attributes and look for the ">" at the end of the leading tag to end up at the beginning of the password.
- From the end of the leading tag I would look for "
This just goes to show what happens when you turn a systems programmer loose on something like SOAP. I made a lot of assumptions and did a less than vigorous parsing of a complicated message. But it works. For now.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at email@example.com.
WS-SecurityPolicy Examples Version 1.0
Committee Specification 02
4 November 2010
OASIS Web Services Secure Exchange TC
Kelvin Lawrence, IBM
Chris Kaler, Microsoft
Rich Levinson, Oracle Corporation
Tony Gullotta, SOA Software Inc.
Symon Chang, Oracle Corporation.
Martin Raepple, SAP AG
Declared XML Namespace(s):
This document contains examples of how to set up WS-SecurityPolicy [WSSP] policies for a variety of common token types that are described in WS-Security 1.0 [WSS10] and WS-Security 1.1 [WSS11] token profiles [WSSTC]. Particular attention is focused on the different “security bindings” (defined in [WSSP]) within the example policies. Actual messages that have been documented in WS-Security TC [WSSTC]and other WS-Security-based Interops [WSSINTEROPS, WSSXINTEROPS, OTHERINTEROPS] that conform to some of the example policies are referenced when appropriate.
The purpose of this document is to give examples of how policies may be defined for several existing use cases that have been part of the WS-Security Interops that have been conducted (see References section for Interop documents [INTEROPS]). In addition, some example use cases have been included which show some variations from the WS-Security Interop use cases in order to demonstrate how different options and security bindings impact the structure of the policies.
This document was last revised or approved by the WS-SX TC on the above date. The level of approval is also listed above. Check the “Latest Version” or “Latest Approved Version” location noted above for possible later revisions of this document.
Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at http://www.oasis-open.org/committees/ws-sx/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-open.org/committees/ws-sx/ipr.php.
Copyright © OASIS® 1993–2010. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The names "OASIS", are trademarks of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
1.1 Terminology and Concepts. 6
1.1.1 Actors. 7
1.1.2 Concepts. 10
22.214.171.124 X509 Certificates. 10
1.2 Terminology. 11
1.3 Normative References. 11
1.4 Non-Normative References. 12
1.5 Specifications. 13
1.6 Interops and Sample Messages. 13
2.1 UsernameToken. 14
2.1.1 UsernameToken – no security binding. 14
126.96.36.199 UsernameToken with plain text password. 14
188.8.131.52 UsernameToken without password. 15
184.108.40.206 UsernameToken with timestamp, nonce and password hash. 16
2.1.2 Use of SSL Transport Binding. 17
220.127.116.11 UsernameToken as supporting token. 17
2.1.3 (WSS 1.0) UsernameToken with Mutual X.509v3 Authentication, Sign, Encrypt19
18.104.22.168 (WSS 1.0) Encrypted UsernameToken with X.509v3. 22
2.1.4 (WSS 1.1), User Name with Certificates, Sign, Encrypt25
2.2 X.509 Token Authentication Scenario Assertions. 29
2.2.1 (WSS1.0) X.509 Certificates, Sign, Encrypt29
2.2.2 (WSS1.0) Mutual Authentication with X.509 Certificates, Sign, Encrypt32
22.214.171.124 (WSS1.0) Mutual Authentication, X.509 Certificates, Symmetric Encryption. 35
2.2.3 (WSS1.1) Anonymous with X.509 Certificate, Sign, Encrypt39
2.2.4 (WSS1.1) Mutual Authentication with X.509 Certificates, Sign, Encrypt42
2.3 SAML Token Authentication Scenario Assertions. 48
2.3.1 WSS 1.0 SAML Token Scenarios. 49
126.96.36.199 (WSS1.0) SAML1.1 Assertion (Bearer)49
188.8.131.52 (WSS1.0) SAML1.1 Assertion (Sender Vouches) over SSL. 51
184.108.40.206 (WSS1.0) SAML1.1 Assertion (HK) over SSL. 53
220.127.116.11 (WSS1.0) SAML1.1 Sender Vouches with X.509 Certificates, Sign, Optional Encrypt54
18.104.22.168 (WSS1.0) SAML1.1 Holder of Key, Sign, Optional Encrypt60
2.3.2 WSS 1.1 SAML Token Scenarios. 65
22.214.171.124 (WSS1.1) SAML 2.0 Bearer65
126.96.36.199 (WSS1.1) SAML2.0 Sender Vouches over SSL. 69
188.8.131.52 (WSS1.1) SAML2.0 HoK over SSL. 71
184.108.40.206 (WSS1.1) SAML1.1/2.0 Sender Vouches with X.509 Certificate, Sign, Encrypt75
220.127.116.11 (WSS1.1) SAML1.1/2.0 Holder of Key, Sign, Encrypt80
2.4 Secure Conversation Scenarios. 105
2.4.1 (WSS 1.0) Secure Conversation bootstrapped by Mutual Authentication with X.509 Certificates. 105
B.Revision History. 118
This document describes several WS-SecurityPolicy [WS-SECURITYPOLICY] examples. An example typically consists of the security aspects of a high-level Web Service use-case with several variable components.Many of the examples are based on existing use cases that have been conducted during WS-Security Interops [WSS-INTEROPS]. In those examples a reference is included to identify the specific use case in the specific interop document that is being demonstrated.
In the policy examples below, the “wsp” prefix refers to the elements defined in the WS-Policy namespace:
the “sp” prefix refers to elements defined in the WS-SecurityPolicy (WS-SP) namespace:
the “t” prefix refers to elements defined in the WS-Trust namespace:
Where uses cases are based on existing scenarios, those scenarios are referenced at the beginning of the use case section. The explicit documents describing the scenarios are identified by links in [Section 3.2].
1.1 Terminology and Concepts
This section (1.1.*) describes the logical “actors” that participate in the examples. In addition, there is a discussion on general concepts that describes how the logical actors typically relate to the physical message exchanges that take place.
This section also provides a security reference model designed to provide context for the examples in terms of a conceptual framework within which the actors interact, which is intended to help readers understand the trust relationships implicit in the message exchanges shown in the examples.
In these examples there are always three important conceptual entities to recognize that exist on the initiating side of a transaction, where the transaction is being requested by sending an electronic message that contains the details of the what is being requested and by whom (the “entities” become “actors” as the discussion moves from the conceptual to the specific). These three entities are:
- The entity requesting the transaction (for example, if the transaction is about an application for a home mortgage loan, then the entity requesting the transaction is the prospective homeowner who will be liable to make the payments on the loan if it is approved).
- The entity approving the transaction to be requested. This entity is generally known as an “identity provider”, or an “authority”, and the purpose of this approving entity is to guarantee to a recipient entity that the requesting entity is making a legitimate request (continuing the above example, the authorizing entity in this case would be the organization that helps the prospective homeowner properly fill out the application, possibly a loan officer at the bank, saying that the loan application is approved for further processing).
- The entity initiating the actual electonic transaction message (in the above example, this entity is simply the technical software used to securely transmit the mortgage application request to a recipient entity that will handle the processing of the mortgage application).
WS-SecurityPolicy is primarily concerned with the technical software used between the initiating entity and the recipient entity, whom are respectively officially referred to as the Initiator and the Recipient in the WS-SecurityPolicy 1.2 specification (WS-SP) (see section 1.4 of that document).
Therefore, the purpose of this section is to give a larger real world context to understanding the examples and how to relate the technical details of WS-SecurityPolicy to the actual logical actors involved in the transactions governed by the technology.
The reason for providing this context is to help interested readers understand that while the technology may be securing the integrity and confidentiality of the messages, there are additional questions about transactions such as who is liable for any commitments resulting from the transaction and how those commitments are technically bound within the message exchanges.
The purpose here is not to provide unequivocable answers to all questions regarding liability of transactions, but to give a sense of how the structuring of a request message ties the participating entities to the transaction. Depending on how the WS-SecurityPolicy technology is used, these “ties” can be relatively stronger or weaker. Depending on the nature of the transactions supported by a particular Web Application, the system managers of the Web Services Application being protected using WS-SecurityPolicy techniques, may be interested in a conceptual framework for understanding which WS-SP techniques are more or less appropriate for their needs.
These introductory sections are intended to provide this type of conceptual framework for understanding how the examples in this document may be interpreted in the above context of the three entities on the initiating side of the transaction. A complementary model is also provided for the recipient side of the transaction, but since the recipient is generally concerned with validating the request, which is primarily a back office function, less emphasis is focused on the options in that environment except as they might relate back to the initiator side of the transaction.
The following diagram shows the actors and the relationships that may be typically involved in a network security scenario:
The diagram is intended to show the possible interactions that may occur between actors in any given scenario, although, in general, depending on the policy specified by the recipient, only a subset of the possible interactions will actually occur in a given scenario. Note that the Issuing and Validating Authorities, may, in general be either a WS-Trust Security Token Service (STS) or other authority.
First, a brief narrative will describe the diagram, then the actors will be defined in more detail.
In a typical example interaction, a Requestor wants to issue a Web Service request to a Web Service that is hosted by the “Recipient” web site on behalf of a RelyingParty, who is actually the business entity responsible for making the service available and with whom any business arrangements with the Requestor are made. One may think of this as an end to end interaction between a Requestor and a RelyingParty, with technical resources being provided by the Initiator on the Requestor side and the Recipient on the RelyingParty side.
Technically, what occurs is that the Requestor hands the request to the Initiator, which in turn issues a query to the Recipient and is returned the WSDL [WSDL] describing the Web Service, which generally includes WS-SP policy Assertions [WS-POLICY, WS-POLICYATTACHMENT] that describe the security policies supported by the Recipient for this Web Service (Note: it is not necessary that the information in the Assertions be obtained this way. It may also be stored locally based on out of band agreements between the Requestor and RelyingParty). This interaction is shown by the upper pair of arrows between the Initiator and the Recipient.
Upon receipt of the WS-SP policy assertions, the Initiator then interacts with the Requestor and the Issuing Authority, as needed in order to meet the requirements specified by the WS-SP. Generally, what is required here is that credentials and tokens are obtained from the Requestor and Issuing Authority and assembled as required in a new WS-Security request message that is to be issued to the Recipient.
(For example, if a UsernameToken is required by the Recipient, one possibility is that the Initiator will query the Requestor for Username and Password and create the appropriate token to include in the Request.
Other possibilities exist as well, but WS-SP only governs what the final message must contain. How it gets constructed and how the pieces are assembled are specific to the system environment that is being used.
In general, the examples in this document will explain the interactions that might occur to meet the policy requirements, but the actual sequences and specifics will be determined by the setup of the systems involved.)
Finally, after assembling the necessary tokens, the Initiator (or Requestor/Initiator) may sign and encrypt the message as required by the WS-SP policy and send it to the Recipient.
Similar to the Requestor side, on the Recipient side, the details of how the Recipient processes the message and uses a Validating Authority to validate the tokens and what basis the RelyingParty uses to accept or reject the request is system specific. However, in a general sense, the 3 actors identified on the Recipient side will be involved to accept and process a request.
(For example, the Recipient may decrypt an encrypted UsernameToken containing a clear text password and username and pass it to the Validating Authority for validation and authentication, then the Recipient may pass the Request to the RelyingParty, which may in turn issue a request for authorization to the Validating Authority.
These details are beyond the scope of WS-SP and the examples in this document, however, knowing that this is the context in which WS-SP operates can be useful to understanding the motivation and usefulness of different examples.)
The following list is a reference to identify the logical actors in Figure 1. (In general, these actors may physically be implemented such that more than one actor is included in the physical entity, such as a Security Token Service (STS) [WS-TRUST] that implements both an IssuingAuthority and a ValidatingAuthority. Similarly, in a scenario where a user is at a security-enabled work station, the work station may combine a Requestor and Initiator in a single physical entity.)
- Requestor: the person or entity requesting the service and who will be supplying credentials issued by the IssuingAuthority and will be validated by a ValidatingAuthority. The Requestor is the logical entity that supplies the credentials that ultimately get passed to the Recipient that will be trusted by the RelyingParty if they are validated by the ValidatingAuthority. (Note: the logistics of supplying the trusted credential is distinct from the logistics of packaging up the credentials within a WS-Security header in a SOAP message and transmitting that message to the Recipient. The latter logistics are covered by the Initiator, described below. The Requestor and Initiator may be combined into a single physical entity and this is a common occurrence, however they do not have to be and it is also a common occurrence that they are separate physical entities. The latter case is typified by the Requestor being a user at a browser that may be promped for credentials by the Initiator on a server using HTTP to challenge the Requestor for a username and password.)
- IssuingAuthority: a Security Token Service (STS), which is an organization or entity that typically issues authentication credentials for Requestors. Examples include X509 Certificate Authority, Saml Token Authority, Kerberos Token Authority. (For user passwords, the IssuingAuthority may be thought of as the entity the user contacts for password services, such as changing password, setting reminder phrases, etc.)
- Initiator: the system or entity that sends the message(s) to the Recipient requesting use of the service on behalf of the Requestor. Typically, the Initiator will first contact the Recipient on behalf of the Requestor and obtain the WS-SP policy and determine what tokens from what kind of IssuingAuthority (X509, SAML, Kerberos, etc) that the Requestor will require to access the service and possibly assist the Requestor to obtain those credentials. In addition, based on the WS-SP policy, the Initiator determines how to format the WS-Security headers of the messages being sent and how to use the security binding required by the policy.
- Recipient: the system or entity or organization that provides a web service for use and is the supplier of the WS-SP policy that is contained in each example and is the recipient of messages sent by Initiators. The Recipient manages all the processing of the request message. It may rely on the services of a ValidatingAuthority to validate the credentials contained in the message. When the Recipient has completed the WS-SP directed processing of the message it will generally be delivered to the RelyingParty which continues processing of the message based on the assurances that the Recipient has established by verifying the message is in compliance with the WS-SP policies that are attached to the service description.
- ValidatingAuthority: the organization or entity that typically validates Requestor credentials for Relying Parties, and, in general, maintains those credentials in an ongoing reliable manner. Typically, the Recipient will request the ValidatingAuthority to validate the credentials before delivering the Request to the RelyingParty for further processing.
- RelyingParty: the organization or entity that relies on the security tokens contained in the messages sent by the Initiator as a basis for providing the service. For this document, the RelyingParty may simply be considered to be the entity that continues processing the message after the Recipient has completed all the processing required by the WS-SP policies attached to the service description.
Of these actors, the Requestor and Initiator can generally being regarded as “client-side” or “requestor-side” actors. The Recipient and RelyingParty (or combined “RelyingParty/Recipient”) can be regarded as “server-side” actors.
Note 1: In addition to the above labelling of the actors, there is also the notion of “Sender”. Generally, the “Sender” may be thought of as a Requestor/Initiator that is independently collecting information from a user (who could be modeled as a separate benign actor to the left of the Requestor in the figure 1.1 from whom the Requestor gathers information that would be included in the message) and is submitting requests on behalf of that user. Generally, the trust of the Recipient is on the Sender, and it is up to the Sender to do whatever is necessary for the Sender to trust the user. Examples of this configuration will be described in the SAML Sender Vouches sections later in this document.
Note 2: The person or entity actually making the request is the "Requestor", however, there are 2 common use cases: 1. the Requestor is a user at a browser and the request is intercepted by a web service that can do WS-Security and this web service is the "Initiator" which actually handles the message protection and passes the Requestor’s credentials (typically collected via http(s) challenge by the Initiator to the Requestor for username/password) to the Recipient. 2. the Requestor is at a web-service client enabled workstation, where the Requestor person making the request is also in charge of the web service client that is initiating the request, in which case the combined entity may be referred to as a "Requestor/Initator".
Physical message exchanges are between the Initiator and Recipient. For the purposes of this document the Initiator and Recipient may be considered to be the physical systems that exchange the messages. The Initiator and Recipient use the keys that are involved in the WS-SP security binding that protects the messages.
As described in the previous section, the Requestor is the logical entity that gathers the credentials to be used in the request and the Initiator is the logical entity that inserts the credentials into the request message and does all the rest of the message construction in accordance with the WS-SP policy. The Requestor may generally be thought of as being either a separate physical entity from the Initiator, oras part of a combined physical entity with the Initiator. An example of the latter combined case would be a user at a client workstation equipped with signing and encryption capabilities, where the combined entity may be referred to as a “Requestor/Initiator”.
Similarly, the IssuingAuthority should generally be thought of as a separate physical entity from the Initiator. However, in some cases, such as SAML sender-vouches, the IssuingAuthority and the Initiator may be the same entity.
In some other cases, such as the case where user passwords are involved, the ValidatingAuthority system entity may also comprise the Recipient and the Relying Party, since passwords are typically checked locally for validity.
The focus of WS-SP is the notion that policy assertions are attached to the Initiator and/or Recipient, however, the concepts in those policies generally require understanding specifically the relation of the parties involved (i.e. Requestor/Initiator, RelyingParty/Recipient). This is because the Requestor in general does not know in advance what policies each Web Service provider requires and it is necessary for practical purposes to have a front end Initiator resolve the policy and coordinate whatever actions are required to exchange the Requestor tokens for the tokens required by the service. This token exchange may be done using WS-Trust [WS-TRUST] to prepare the necessary requests and process responses from an STS IssuingAuthority. Examples of these WS-Trust token exchanges may be found in [WSSX-INTEROP].
Typically both the Requestor/Initiator and Recipient/RelyingParty will have relations with the IssuingAuthority/ValidatingAuthority and often establish contact with those Authorities using WS-Trust for the purpose of obtaining and validating tokens used in their Web Service interactions. The policies for using the Authority may also be represented using WS-SP, but they are typically no different from the policies shown in the examples in this document. The policies in this document may be used for any kind of request, whether it be a request to a service provider for general content or operations or a request to an Authority for authentication tokens.
In each example the relations between these actors and how the request message is prepared will be described, because, in general, the policy requirements will imply these relationships. Generally, each of the 3 client side actors, the Requestor, the Initiator, and the IssuingAuthority will contribute to the preparation of the request message, which is the primary focus of this document. For validation of the message, the Recipient, the RelyingParty, and the ValidatingAuthority are generally involved, but for this document the focus is simply that the Recipient provides the WS-SP policy that dictates the preparation of the request message.
18.104.22.168 X509 Certificates
The specifics of whom is trusted for X509 certificates depends on the specific organization’s PKI (Public Key Infrastructure) setup. For this document, we shall assume the Subject of the X509 certificate identifies the actor, which may be the IssuingAuthority, or the Initiator, or the Requestor, depending on the example. We shall also assume that the issuer of the X509 certificates is a general Certificate Authority not directly involved in any authorization of the web service transactions, but is relied on for the validity of the X509 certificate in a manner out of scope of the scenarios covered. In addition, this document does not explicitly address the case of X509 certificates issued by the IssuingAuthority actor. Such use cases are generally implicitly covered if one assumes that such relations are automatically covered by the specifics of the organization PKI setups.
However, the IssuingAuthority may issue tokens, such as SAML holder-of-key that contain X509 certificates. In these cases, the basis of trust is that the X509 Certificate of the IssuingAuthority was used to protect the X509 certificate of the Requestor which is contained in the signed SAML holder-of-key token. I.e. any “chaining” of tokens is done by referencing those tokens within signed XML structures and not by issuing actual X509 certificates
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
1.3 Normative References
[RFC2119]S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
[WSS10-SOAPMSG] OASIS Standard, “Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)”, March 2004.
[WSS11-SOAPMSG] OASIS Standard, “Web Services Security: SOAP Message Security 1.1”, OASIS Standard incorporating Approved Errata, 01 November 2006.
[WSS10-USERNAME] OASIS Standard, “Web Services Security: UsernameToken Profile 1.0”, March 2004.
[WSS11-USERNAME] OASIS Standard, “Web Services Security: UsernameToken Profile 1.1”, February 2006.
[WSS10-X509-PROFILE]OASIS Standard, “Web Services Security: X.509 Certificate Token Profile 1.0”, March 2004.
[WSS11-X509-PROFILE]OASIS Standard, “Web Services Security: X.509 Certificate Token Profile 1.1”, OASIS Standard incorporating Approved Errata, 01 November 2006.
[WSS10-SAML11-PROFILE]OASIS Standard, “Web Services Security: SAML Token Profile 1.0”, December 2004.
[WSS11-SAML1120-PROFILE]OASIS Standard, “Web Services Security: SAML Token Profile 1.1”, OASIS Standard Incorporating Approved Errata, 1 November 2006.
[WSS-TC-ALL-TOKEN-PROFILES]OASIS WS-Security TC links to all other WSS 1.0 and WSS 1.1 token profiles
and other documents (interops) in the TC repository:
[WS-SECURITYPOLICY]OASIS Standard, “WS-SecurityPolicy 1.2”, July 2007.
[WS-SECURECONVERSATION] OASIS Standard, “WS-SecureConversation 1.3”, March 2007. http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/ws-secureconversation-1.3-os.doc
[WS-TRUST]OASIS Standard, “WS-Trust 1.3”, March 2007.
[SAML11-CORE]OASIS Standard, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V1.1”, September 2003.
[SAML20-CORE]OASIS Standard, “Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0”, March 2005.
1.4 Non-Normative References
WSS10-INTEROP-01:OASIS Working Draft 06, “Web Services Security: Interop 1 Scenarios”, Jun 2003.
WSS10-INTEROP-02: OASIS Working Draft 06, “Web Services Security: Interop 2 Scenarios”, Oct 2003.
WSS11-INTEROP-01: OASIS Working Draft 02, “Web Services Security 1.1: Interop Scenario”, June 2005. http://www.oasis-open.org/committees/download.php/12997/wss-11-interop-draft-01.doc
WSS10-KERBEROS-INTEROP:OASIS Working Draft 02, “Web Services Security: Kerberos Token Profile Interop Scenarios”, Jan 2005.
WSS10-SAML11-INTEROP:OASIS Working Draft 12, “Web Services Security: SAML Interop 1 Scenarios”, July 2004.
WSS11-SAML1120-INTEROP:OASIS Working Draft 4, “Web Services Security: SAML 2.0Interop Scenarios”, January 2005.
WSSX-PRE-INTEROP:OASIS Contribution Version 1.0d,“WS-SecureConversation and WS-Trust Interop Scenarios”, September 29, 2004.
WSSX-WSTR-WSSC-INTEROP: OASIS White Paper Version ED-10, “WS-SX Interop Scenarios - Phase 2 Scenarios for demonstration of WS-SX TC specifications”, October 31, 2006. http://www.oasis-open.org/committees/download.php/20954/ws-sx-interop-ed-10.doc
WS-SECURE-INTEROP: OASIS White Paper Version ED-01, “Examples of Secure Web Service Message Exchange”, July 11, 2008.
WSI-SCM-SAMPLEAPPL:http://java.sun.com/webservices/docs/1.4/wsi-sampleapp/index.html (login required)
1.6 Interops and Sample Messages
UsernameToken authentication scenarios that use simple username password token for authentication. There are several sub-cases.
2.1.1 UsernameToken – no security binding
In this model a UsernameToken is placed within a WS-Security header in the SOAP Header [WSS10-USERNAME, WSS11-USERNAME]. No other security measure is used.
Because no security binding is used, there is no explicit distinction between the Requestor, who is identified in the UsernameToken and the Initiator, who physically sends the message. They may be one and the same or distinct parties. The lack of a security binding indicates that any direct URL access method (ex. HTTP) may be used to access the service.
22.214.171.124 UsernameToken with plain text password
This scenario is based on the first WS-Security Interop Scenarios Document [WSS10-INTEROP-01 Scenario 1 – section 3.4.4]
This policy says that Requestor/Initiator must send a password in a UsernameToken in a WS-Security header to the Recipient (who as the Authority will validate the password). The password is required because that is the default requirement for the Web Services Security Username Token Profile 1.x [WSS10-USERNAME, WSS11-USERNAME].
This setup is only recommended where confidentiality of the password is not an issue, such as a pre-production test scenario with dummy passwords, which might be used to establish that the Initiator can read the policy and prepare the message correctly, and that connectivity and login to the service can be performed.
(P004) <sp:UsernameToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"
An example of a message that conforms to the above stated policy is as follows.
(M001) <?xml version="1.0" encoding="utf-8" ?>
(M002) <soap:Envelope xmlns:soap="...">
(M004) <wsse:Security soap:mustUnderstand=“1”xmlns:wsse="...">
(M007) <wsse:Password Type=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText”>sirhC</wsse:Password>
(M008) <wsse:Nonce EncodingType="...#Base64Binary"
(M015) <Ping xmlns="http://xmlsoap.org/Ping">