The IVOA standard for single-sign-on authentication with web services requires SOAP message-level security using the WS-Security standard of OASIS. This document specifies the set of XML elements from WS-Security that must be used in secured messages to IVOA services. The required actions by the sender and receiver of the messages are also specified.
This is a Working Draft. This is the first release.
This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress.A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.
The IVOA profile for single-sign-on authentication with web services, of which this document is a part, requires that authentication be done by digital signature of SOAP messages plus the inclusion of identity warrants signed by a certificate authortity. The profile further requires that the credentials for authentication be carried in the SOAP header of messages in accordance with the WS-Security standard of OASIS [WS-Security, WS-Security-TC, OASIS]. The background for these requirements is described in the introduction to the IVOA profile.
The current document specifies the exact elements from WS-Security [WS-Security] that must be used in secured messages to IVOA services. The actions by the sender in composing the message and by the receiver in verifying it are also specified.
In the following sections, types of XML elements are specified by namespace-qualified names, e.g. wss:Security. The namespaces used are as follows.
All material relating to the security of a SOAP message shall be carried in the SOAP header of the message. The sole exception to this rule is that the soap-env:Body element carrying the message body shall have a wsu:Id attribute used in the writing of the digital signature.
All the security material shall be contained in an element of type wss:Security.
The message shall include tokens to prove uniqueness and thus to guard against 'replay' attacks. There shall be a wsu:Timestamp element directly inside the wss:Security element. The wsu:Timestamp must have a wsu:Id attribute to allow it to be digitally signed.
The wsu:Timestamp shall contain a wss:Nonce and a wsu:Created. The value of the former shall be random such that the chance of two messages to the same service, within the lifetime of that service, having the same nonce is negligible. The value of the latter shall be the absolute time at which the message was written; the sender shall use this datum to determine the age of the message.
The message shall contain one or more identity warrants that bind an identity to a public cryptographic key and thus link the identity to the signed parts of the message.
The sender may use multiple warrants either to express mutiple identities; or to express one identity vouched for by more than one certficate authority; or some combination of these two uses. On receiving multiple warrants, a service must use the union of the identities in determining authorization.
A message may be constructed with a digital signature according to WS-Security but no identity warrants. Such a message is effectively anonymous, since there is no way of authenticating any identity in the message. It may sometimes be useful to send a anonymous message whose integratity is protected by signatire, but such a message is not part of the IVOA SSO profile.
Identity warrants must be X.509v3 certficates. Contrary to what has been written in the introduction to the IVOA SSO profile, warrants may not at this time be SAML assertions; however, SAML assertions may be included in a later version of this standard. At present, the proper use of SAML with WS-Security is very unclear and trying to support SAML might slow down standardization. It is of more benefit to support X.509 quickly than delay until SAML is understood.
X.509 certificates must be included as wss:BinarySecurityToken elements inside the wss:Security element. The attributes and content of these elements must follow the rules of the WSS-Security profile for X.509 certificates [WS-Security-X509].
The body of the message shall be digitally signed by the sender using the private key of a public-private key-pair. This key-pair must be the one associated with the identity to be authenticated by the accompanying identity warrants.
The signature shall be written as a ds:Signature element. It shall follow the rules of WS-Security section 8 [WS-Security] and standards referenced therein. The signature shall include a ds:SignedInfo element and the latter shall include a ds:Reference element in which the value of the URI attribute matches the value of the wsu:Id attribute on the message body.
The wsu:Timestamp in the wss:Security shall be digitally signed by the sender using the private key of a public-private key-pair. This key-pair must be the one associated with the identity to be authenticated by the accompanying identity warrants.
The signature shall be written as a ds:Signature element. It shall follow the rules of WS-Security section 8 [WS-Security] and standards referenced therein. The signature shall include a ds:SignedInfo element and the latter shall include a ds:Reference element in which the value of the URI attribute matches the value of the wsu:Id attribute on the timestamp.
The sender of a message should follow this procedure in adding a security header to the message. (Note that any alternative procedure is valid if it achieves a header following the rules defined and quoted above for the content of the message.)
Note that the receiver of the message will reject messages whose timestamp preceeds the time of reception by more than a certain interval, and that this time-out interval may be as short as a few minutes. Therefore, the message must be sent promptly after its timestamp is created.
The receiver of a message shall determine the identity of the sender from the identity or identities bound in the included warrants. The receiver should consider those identities valid for access control only if they can be authenticated, and shall consider an identity authenticated only if the following list of checks are all passed. Note that the order of the checks is unimportant.
The receiver must then remember the nonce of the message for use in checking the uniqueness of subsequent messages. The receiver need not remember nonces for ever, but may forget them after some fixed duration. However, the receiver must not accept any messages so old that it would have forgotten the nonce. The receiver may choose the length of its memory for nonces. However, general services should remember nonces for at least five minutes.