Web Services Security:
SAML Token Profile 1.1

OASIS Public Review Draft 01, 28 June 2005

Document Identifier:

wss-v1.1-spec-pr-SAMLTokenProfile-01

OASIS Identifier:

{WSS: SOAP Message Security }-{SAMLTokenProfile}-{1.1} (OpenOffice) (PDF) (HTML)

Location:

Persistent: [persistent location]

This Version: http://docs.oasis-open.org/wss/oasis-wss-SAMLTokenProfile-1.1

Previous Version:http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0

Technical Committee:

OASIS Web Services Security (WSS) TC

Chairs:

Kelvin Lawrence, IBM

Chris kaler, Microsoft

Editors:

Ronald Monzillo, Sun

Chris kaler, Microsoft

Anthony Nadalin, IBM

Phillip Hallam-Baker, Verisign

Abstract:

This document describes how to use Security Assertion Markup Language (SAML) V1.1 and V2.0 assertions with the Web Services Security (WSS): SOAP Message Security V1.1 specification.

With respect to the description of the use of SAML V1.1, this document subsumes and is totally consistent with the Web Services Security: SAML Token Profile 1.0.

Status:

This document was last revised or approved by the membership of the Web Services Security TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

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 www.oasis-open.org/committees/wss.

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 (www.oasis-open.org/committees/wss/ipr.php).

The non-normative errata for this specification is located at www.oasis-open.org/committees/wss.

Notices

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's procedures with respect to rights in OASIS specifications can be found at 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 implementors or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 2002-2005. All Rights Reserved.

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 paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document 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 RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1Introduction

The WSS: SOAP Message Security specification defines a standard set of SOAP extensions that implement SOAP message authentication and encryption. This specification defines the use of Security Assertion Markup Language (SAML) assertions as security tokens from the <wsse:Security> header block defined by the WSS: SOAP Message Security specification.

1.1Goals

The goal of this specification is to define the use of SAML V1.1 and V2.0 assertions in the context of WSS: SOAP Message Security including for the purpose of securing SOAP messages and SOAP message exchanges. To achieve this goal, this profile describes how:

1. SAML assertions are carried in and referenced from <wsse:Security> Headers.

2. SAML assertions are used with XML signature to bind the subjects and statements of the assertions (i.e., the claims) to a SOAP message.

1.1.1Non-Goals

The following topics are outside the scope of this document:

1. Defining SAML statement syntax or semantics.

2. Describing the use of SAML assertions other than for SOAP Message Security.

3. Describing the use of SAML V1.0 assertions with the Web Services Security (WSS): SOAP Message Security specification.

2Notations and Terminology

This section specifies the notations, namespaces, and terminology used in this specification.

2.1Notational Conventions

The keywords "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.

This document uses the notational conventions defined in the WS-Security SOAP Message Security document.

Namespace URIs (of the general form "some-URI") represent some application-dependent or context-dependent URI as defined in RFC2396.

This specification is designed to work with the general SOAP message structure and message processing model, and should be applicable to any version of SOAP. The current SOAP 1.2 namespace URI is used herein to provide detailed examples, but there is no intention to limit the applicability of this specification to a single version of SOAP.

Readers are presumed to be familiar with the terms in the Internet Security Glossary.

2.2Namespaces

The appearance of the following [XML-ns] namespace prefixes in the examples within this specification should be understood to refer to the corresponding namespaces (from the following table) whether or not an XML namespace declaration appears in the example:

Table-1 Namespace Prefixes

2.3Terminology

This specification employs the terminology defined in the WSS: SOAP Message Security specification. The definitions for additional terminology used in this specification appear below.

Attesting Entity – the entity that provides the confirmation evidence that will be used to establish the correspondence between the subjects and claims of SAML statements (in SAML assertions) and SOAP message content.

Confirmation Method Identifier – the value within a SAML SubjectConfirmation element that identifies the subject confirmation process to be used with the corresponding statements.

Subject Confirmation – the process of establishing the correspondence between the subject and claims of SAML statements (in SAML assertions) and SOAP message content by verifying the confirmation evidence provided by an attesting entity.

SAML Assertion Authority - A system entity that issues assertions.

Subject – A representation of the entity to which the claims in one or more SAML statements apply.

3Usage

This section defines the specific mechanisms and procedures for using SAML assertions as security tokens.

3.1Processing Model

This specification extends the token-independent processing model defined by the WSS: SOAP Message Security specification.

When a receiver processes a <wsse:Security> header containing or referencing SAML assertions, it selects, based on its policy, the signatures and assertions that it will process. It is assumed that a receiver’s signature selection policy MAY rely on semantic labeling¹ of <wsse:SecurityTokenReference> elements occurring in the <ds:KeyInfo> elements within the signatures. It is also assumed that the assertions selected for validation and processing will include those referenced from the <ds:KeyInfo> and <ds:SignedInfo> elements of the selected signatures.

As part of its validation and processing of the selected assertions, the receiver MUST² establish the relationship between the subject and claims of the SAML statements (of the referenced SAML assertions) and the entity providing the evidence to satisfy the confirmation method defined for the statements (i.e., the attesting entity). Two methods for establishing this correspondence, holder-of-key and sender-vouches are described below. Systems implementing this specification MUST implement the processing necessary to support both of these subject confirmation methods.

3.2SAML Version Differences

The following sub-sections describe the differences between SAML V1.1 and V2.0 that apply to this specification.

3.2.1Assertion Identifier

In SAML V1.1 the name of the assertion identifier attribute is “AssertionID”. In SAML v2.0 the name of the assertion identifier attribute is “ID”. In both versions the type of the identifier attribute is xs:ID.

3.2.2Relationship of Subjects to Statements

A SAML assertion contains a collection of 0 or more statements. In SAML V1.1, a separate subject with separate subject confirmation methods may be specified for each statement of an assertion. In SAML V2.0, at most one subject and at most one set of subject confirmation methods may be specified for all the statements of the assertion. These distinctions are described in more detail by the following paragraphs.

A SAML V1.1 statement that contains a <saml:Subject> element (i.e., a subject statement) may contain a <saml:SubjectConfimation> element that defines the rules for confirming the subject and claims of the statement. If present, the <saml:SubjectConfirmation> element occurs within the subject element, and defines one or more methods (i.e., <saml:ConfirmationMethod> elements) by which the statement may be confirmed and will include a <ds:KeyInfo>³ element when any of the specified methods are based on demonstration of a confirmation key. The <saml:SubjectConfirmation> element also provides for the inclusion of additional information to be applied in the confirmation method processing via the optional <saml:SubjectConfirmationData> element. The following example depicts a SAML V1.1 assertion containing two subject statements with different subjects and different subject confirmation elements.

<saml:Assertion

…

<saml:SubjectStatement>

<saml:Subject>

<saml:NameIdentifier

…

</saml:NameIdentifier>

<saml:SubjectConfirmation>

<saml:ConfirmationMethod>

urn:oasis:names:tc:SAML:1.0:cm:sender-vouches

</saml:ConfirmationMethod>

<saml:ConfirmationMethod>

urn:oasis:names:tc:SAML:1.0:cm:holder-of-key

</saml:ConfirmationMethod>

<ds:KeyInfo>

<ds:KeyValue>…</ds:KeyValue>

</ds:KeyInfo>

</saml:SubjectConfirmation>

</saml:Subject>

….

</saml:SubjectStatement>

<saml:SubjectStatement>

<saml:Subject>

<saml:NameIdentifier

…

</saml:NameIdentifier>

<saml:SubjectConfirmation>

<saml:ConfirmationMethod>

urn:oasis:names:tc:SAML:1.0:cm:sender-vouches

</saml:ConfirmationMethod>

</saml:SubjectConfirmation>

</saml:Subject>

….

</saml:SubjectStatement>

…

</saml:Assertion>

A SAML V2.0 assertion may contain a single <saml2:Subject> that applies to all the statements of the assertion. When a subject is included in A SAML V2.0 assertion, it may contain any number of <saml2:SubjectConfimation> elements, satisfying any of which is sufficient to confirm the subject and all the statements of the assertion. Each <saml2:SubjectConfirmation> element identifies a single confirmation method (by attribute value) and may include an optional <saml2:SubjectConfirmationData> element that is used to specify optional confirmation method independent condition attributes and to define additional method specific confirmation data. In the case of a key dependent confirmation method, a <saml2:KeyInfoConfirmationDataType> that includes 1 or more <ds:KeyInfo> elements is included as <saml2:SubjectConfirmationData>. In this case, each <ds:KeyInfo> element identifies a key that may be demonstrated to confirm the assertion. The following example depicts a SAML V2.0 assertion containing a subject with multiple confirmation elements that apply to all the statements of the assertion.

<saml2:Assertion

…

<saml2:Subject>

<saml2:NameID>

…

</saml2:NameID>

<saml2:SubjectConfirmation

Method=”urn:oasis:names:tc:SAML:2.0:cm:sender-vouches”>

<saml2:SubjectConfirmationData>

Address=”129.148.9.42”

</saml2:SubjectConfirmationData>

</saml2:SubjectConfirmation>

<saml2:SubjectConfirmation

Method=”urn:oasis:names:tc:SAML:2.0:cm:holder-of-key”>

<saml2:KeyInfoSubjectConfirmationData>

<ds:KeyInfo>

<ds:KeyValue>…</ds:KeyValue>

</ds:KeyInfo>

</saml2:KeyInfoSubjectConfirmationData>

<saml2:SubjectConfirmation>

</saml2:Subject>

….

<saml2:Statement>

…

</saml2:Statement>

<saml2:Statement>

…

</saml2:Statement>

…

</saml2:Assertion>

3.2.3Assertion URI Reference Replaces AuthorityBinding

SAML V1.1 defines the (deprecated) <saml:AuthorityBinding> element so that a relying party can locate and communicate with an assertion authority to acquire a referenced assertion.

The <saml:AuthorityBinding> element was removed from SAML V2.0. [SAMLBindV2] requires that an assertion authority support a URL endpoint at which an assertion will be returned in response to an HTTP request with a single query string parameter named ID.

For example, if the documented endpoint at an assertion authority is:

https://saml.example.edu/assertion-authority

then the following request will cause the assertion with ID “abcde” to be returned:

https://saml.example.edu/assertion-authority?ID=abcde

3.2.4Attesting Entity Identifier

The <saml2:SubjectConfirmation> element of SAML V2.0 provides for the optional inclusion of an element (i.e., NameID) to identify the expected attesting entity as distinct from the subject of the assertion.

<saml2:SubjectConfirmation

Method=”urn:oasis:names:tc:SAML:2.0:cm:sender-vouches”>

<NameID>

gateway

</NameID>

<saml2:SubjectConfirmationData>

Address=”129.148.9.42”

</saml2:SubjectConfirmationData>

</saml2:SubjectConfirmation>

3.3Attaching Security Tokens

SAML assertions are attached to SOAP messages using WSS: SOAP Message Security by placing assertion elements or references to assertions inside a <wsse:Security> header. The following example illustrates a SOAP message containing a bearer confirmed SAML V1.1 assertion in a <wsse:Security> header.

<S12:Envelope>

<S12:Header>

<wsse:Security>

<saml:Assertion

AssertionID="_a75adf55-01d7-40cc-929f-dbd8372ebdfc"

IssueInstant="2003-04-17T00:46:02Z"

Issuer=”www.opensaml.org”

MajorVersion="1"

MinorVersion="1"

. . .

<saml:AuthenticationStatement>

<saml:Subject>

<saml:NameIdentifier

NameQualifier="www.example.com"

Format=“urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName”>

uid=joe,ou=people,ou=saml-demo,o=baltimore.com

</saml:NameIdentifier>

<saml:SubjectConfirmation>

<saml:ConfirmationMethod>

urn:oasis:names:tc:SAML:1.0:cm:bearer

</saml:ConfirmationMethod>

</saml:SubjectConfirmation>

</saml:Subject>

</saml:AuthenticationStatement>

</saml:Assertion>

</wsse:Security>

</S12:Header>

<S12:Body>

. . .

</S12:Body>

</S12:Envelope>

3.4Identifying and Referencing Security Tokens

The WSS: SOAP Message Security specification defines the <wsse:SecurityTokenReference> element for referencing security tokens. Three forms of token references are defined by this element and the element schema includes provision for defining additional reference forms should they be necessary. The three forms of token references defined by the <wsse:SecurityTokenReference> element are defined as follows:

• A key identifier reference – a generic element (i.e., <wsse:KeyIdentifier>) that conveys a security token identifier as an <wsse:EncodedString> and indicates in its attributes (as necessary) the key identifier type (i.e., the ValueType), the identifier encoding type (i.e., the EncodingType), and perhaps other parameters used to reference the security token.

  When a key identifier is used to reference a SAML assertion, it MUST contain as its element value the corresponding SAML assertion identifier. The key identifier MUST also contain a ValueType attribute and the value of this attribute MUST be the value from Table 2 corresponding to the version of the referenced assertion. The key identifier MUST NOT include an EncodingType⁴ attribute and the element content of the key identifier MUST be encoded as xsi:string.

  When a key identifier is used to reference a V1.1 SAML assertion that is not contained in the same message as the key identifier, a <saml:AuthorityBinding> element MUST be contained in the <wsse:SecurityTokenReference> element containing the key identifier. The contents of the <saml:AuthorityBinding> element MUST contain values sufficient for the intended recipients of the <wsse:SecurityTokenReference> to acquire the identified assertion from the intended Authority. To this end, the value of the AuthorityKind attribute of the <saml:AuthorityBinding> element MUST be “samlp:AssertionIdReference”.

  When a key Identifier is used to reference a SAML assertion contained in the same message as the key identifier, a <saml:AuthorityBinding> element MUST NOT be included in the <wsse:SecurityTokenReference> containing the key identifier.

  A key identifier MUST NOT be used to reference a SAML V2.0 assertion if the assertion is NOT contained in the same message as the key identifier.

• A Direct or URI reference – a generic element (i.e., <wsse:Reference>) that identifies a security token by URI. If only a fragment identifier is specified, then the reference is to the security token within the document whose local identifier (e.g., <wsu:Id> attribute) matches the fragment identifier. Otherwise, the reference is to the (potentially external) security token identified by the URI.

  A reference to a SAML V2.0 assertion that is NOT contained in the same message MUST be a Direct or URI reference. In this case, the value of the URI attribute must conform to the URI syntax defined in section 3.7.5.1 of [SAMLBindV2]. That is, an HTTP or HTTPS request with a single query string parameter named ID. The reference MUST also contain a wsse11:TokenType attribute and the value of this attribute MUST be the value from Table 3 identifying the assertion as a SAML V2.0 security token. When a Direct reference is made to a SAML V2.0 Assertion, the Direct reference SHOULD NOT contain a ValueType attribute.

  This profile does not describe the use of Direct or URI references to reference V1.1 SAML assertions.

• An Embedded reference – a reference that encapsulates a security token.

  When an Embedded reference is used to encapsulate a SAML assertion, the SAML assertion MUST be included as a contained element within a <wsse:Embedded> element within a <wsse:SecurityTokenReference>.

This specification describes how SAML assertions may be referenced in four contexts:

• A SAML assertion may be referenced directly from a <wsse:Security> header element. In this case, the assertion is being conveyed by reference in the message.

• A SAML assertion may be referenced from a <ds:KeyInfo> element of a <ds:Signature> element in a <wsse:Security> header. In this case, the assertion contains a SubjectConfirmation element that identifies the key used in the signature calculation.

• A SAML assertion reference may be referenced from a <ds:Reference> element within the <ds:SignedInfo> element of a <ds:Signature> element in a <wsse:Security> header. In this case, the doubly-referenced assertion is signed by the containing signature.

• A SAML assertion reference may occur as encrypted content within an <xenc:EncryptedData> element referenced from a <xenc:DataReference> element within an <xenc:ReferenceList> element. In this case, the assertion reference (which may contain an embedded assertion) is encrypted.

In each of these contexts, the referenced assertion may be:

• local – in which case, it is included in the <wsse:Security> header containing the reference.

• remote – in which case it is not included in the <wsse:Security> header containing the reference, but may occur in another part of the SOAP message or may be available at the location identified by the reference which may be an assertion authority.

A SAML key identifier reference MUST be used for all (local and remote) references to SAML 1.1 assertions. All (local and remote) references to SAML V2.0 assertions SHOULD be by Direct reference and all remote references to V2.0 assertions MUST be by Direct reference URI. A key identifier reference MAY be used to reference a local V2.0 assertion. To maintain compatibility with Web Services Security: SOAP Message Security 1.0, the practice of referencing local SAML 1.1 assertions by Direct <wsse:SecurityTokenReference> reference is not defined by this profile.

Every key identifier, direct, or embedded reference to a SAML assertion SHOULD contain a wsse11:TokenType attribute and the value of this attribute MUST be the value from Table 3 that identifies the type and version of the referenced security token. When the referenced assertion is a SAML V2.0 Assertion the reference MUST contain a wsse11:TokenType attribute (as described above).

Table-2 Key Identifier ValueType Attribute Values

Table-3 TokenType Attribute Values

The following subsections define the SAML assertion references that MUST be supported by conformant implementations of this profile. A conformant implementation may choose to support the reference forms corresponding to either or both V1.1 or V2.0 SAML assertions.

3.4.1SAML Assertion Referenced from Header or Element

All conformant implementations MUST be able to process SAML assertion references occurring in a <wsse:Security> header or in a header element other than a signature to acquire the corresponding assertion. A conformant implementation MUST be able to process any such reference independent of the confirmation method of the referenced assertion.

A SAML assertion may be referenced from a <wsse:Security> header or from an element (other than a signature) in the header. The following example demonstrates the use of a key identifier in a <wsse:Security> header to reference a local SAML V1.1 assertion.

<S12:Envelope>

<S12:Header>

<wsse:Security>

<saml:Assertion

AssertionID="_a75adf55-01d7-40cc-929f-dbd8372ebdfc"

IssueInstant="2003-04-17T00:46:02Z"

Issuer=”www.opensaml.org”

MajorVersion="1"

MinorVersion="1"

. . .

</saml:Assertion>

<wsse:SecurityTokenReference wsu:Id=”STR1”

wsse11:TokenType=”http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1”>

<wsse:KeyIdentifier wsu:Id=”…”

ValueType=”http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID”>

_a75adf55-01d7-40cc-929f-dbd8372ebdfc

</wsse:KeyIdentifier>

</wsse:SecurityTokenReference>

</wsse:Security>

</S12:Header>

<S12:Body>

. . .

</S12:Body>

</S12:Envelope>

The following example depicts the use of a key identifier reference to reference a local SAML V2.0 assertion.

<wsse:SecurityTokenReference

wsu:Id=”STR1”

wsse11:TokenType=”http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0”>

<wsse:KeyIdentifier wsu:Id=”…”

ValueType=”http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID”>

_a75adf55-01d7-40cc-929f-dbd8372ebdfc