[MS-SAMLPR]:
Security Assertion Markup Language (SAML) Proxy Request Signing Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
§ Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
§ Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
§ No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
§ Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
§ License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.
§ Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit www.microsoft.com/trademarks.
§ Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Support. For questions and support, please contact .
Revision Summary
Date / Revision History / Revision Class / Comments /3/12/2010 / 1.0 / Major / First Release.
4/23/2010 / 1.0.1 / Editorial / Changed language and formatting in the technical content.
6/4/2010 / 1.0.2 / Editorial / Changed language and formatting in the technical content.
7/16/2010 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
8/27/2010 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
10/8/2010 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
11/19/2010 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
1/7/2011 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
2/11/2011 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
3/25/2011 / 1.0.2 / None / No changes to the meaning, language, or formatting of the technical content.
5/6/2011 / 2.0 / Major / Updated and revised the technical content.
6/17/2011 / 3.0 / Major / Updated and revised the technical content.
9/23/2011 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
12/16/2011 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
3/30/2012 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/12/2012 / 3.1 / Minor / Clarified the meaning of the technical content.
10/25/2012 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
1/31/2013 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
11/14/2013 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
2/13/2014 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
5/15/2014 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
6/30/2015 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
7/14/2016 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
6/1/2017 / 3.1 / None / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1 Introduction 7
1.1 Glossary 7
1.2 References 8
1.2.1 Normative References 8
1.2.2 Informative References 9
1.3 Overview 9
1.4 Relationship to Other Protocols 9
1.5 Prerequisites/Preconditions 10
1.6 Applicability Statement 10
1.7 Versioning and Capability Negotiation 10
1.8 Vendor-Extensible Fields 11
1.9 Standards Assignments 11
2 Messages 12
2.1 Transport 12
2.2 Common Message Syntax 12
2.2.1 Namespaces 12
2.2.2 Messages 12
2.2.2.1 SignMessageRequest 13
2.2.2.2 SignMessageResponse 14
2.2.2.3 VerifyMessageRequest 14
2.2.2.4 VerifyMessageResponse 15
2.2.2.5 IssueRequest 15
2.2.2.6 IssueResponse 16
2.2.2.7 LogoutRequest 16
2.2.2.8 LogoutResponse 17
2.2.2.9 CreateErrorMessageRequest 18
2.2.2.10 CreateErrorMessageResponse 18
2.2.3 Elements 19
2.2.4 Complex Types 19
2.2.4.1 RequestType 19
2.2.4.2 ResponseType 19
2.2.4.3 PrincipalType 19
2.2.4.4 SamlMessageType 20
2.2.4.5 PostBindingType 20
2.2.4.6 RedirectBindingType 21
2.2.5 Simple Types 21
2.2.5.1 LogoutStatusType 21
2.2.5.2 PrincipalTypes 22
2.2.6 Attributes 22
2.2.7 Groups 22
2.2.8 Attribute Groups 22
3 Protocol Details 23
3.1 Common Details 23
3.1.1 Abstract Data Model 23
3.1.2 Timers 23
3.1.3 Initialization 23
3.1.4 Message Processing Events and Sequencing Rules 23
3.1.4.1 SignMessage 24
3.1.4.1.1 Messages 24
3.1.4.1.1.1 SignMessageRequest 24
3.1.4.1.1.2 SignMessageResponse 24
3.1.4.2 VerifyMessage 24
3.1.4.2.1 Messages 24
3.1.4.2.1.1 VerifyMessageRequest 24
3.1.4.2.1.2 VerifyMessageResponse 24
3.1.4.3 Issue 25
3.1.4.3.1 Messages 25
3.1.4.3.1.1 IssueRequest 25
3.1.4.3.1.2 IssueResponse 25
3.1.4.4 Logout 25
3.1.4.4.1 Messages 25
3.1.4.4.1.1 LogoutRequest 25
3.1.4.4.1.2 LogoutResponse 25
3.1.4.5 CreateErrorMessage 25
3.1.4.5.1 Messages 26
3.1.4.5.1.1 CreateErrorMessageRequest 26
3.1.4.5.1.2 CreateErrorMessageResponse 26
3.1.4.6 Types Common to Multiple Operations 26
3.1.4.6.1 Complex Types 26
3.1.4.6.1.1 PrincipalType 26
3.1.4.6.1.2 SamlMessageType 26
3.1.4.6.1.3 PostBindingType 26
3.1.4.6.1.4 RedirectBindingType 27
3.1.4.6.2 Simple Types 27
3.1.4.6.2.1 LogoutStatusType 27
3.1.4.6.2.2 PrincipalTypes 27
3.1.4.7 Status Codes for Operations 27
3.1.4.7.1 Element <Status> 27
3.1.4.7.2 Element <StatusCode> 28
3.1.4.7.3 Element <StatusMessage> 30
3.1.4.7.4 Element <StatusDetail> 30
3.1.5 Timer Events 30
3.1.6 Other Local Events 30
3.2 Server Details 30
3.2.1 Abstract Data Model 30
3.2.2 Timers 30
3.2.3 Initialization 31
3.2.4 Message Processing Events and Sequencing Rules 31
3.2.5 Timer Events 31
3.2.6 Other Local Events 31
3.3 Client Details 31
3.3.1 Abstract Data Model 31
3.3.2 Timers 31
3.3.3 Initialization 31
3.3.4 Message Processing Events and Sequencing Rules 31
3.3.5 Timer Events 31
3.3.6 Other Local Events 32
4 Protocol Examples 33
4.1 Issue Operation Examples 33
4.1.1 IssueRequest Example 33
4.1.2 IssueResponse Example 34
4.1.3 IssueResponse Example Using Artifact Binding 35
4.2 CreateErrorMessage Operation Examples 36
4.2.1 CreateErrorMessageRequest Example 36
4.2.2 CreateErrorMessageResponse Example 37
4.3 SignMessage Operation Examples 37
4.3.1 SignMessageRequest Example 37
4.3.2 SignMessageResponse Example 38
4.4 VerifyMessage Operation Examples 39
4.4.1 VerifyMessageRequest Example 39
4.4.2 VerifyMessageResponse Example 40
4.4.3 VerifyMessageResponse Example Using Redirect Binding 40
4.5 Logout Operations Examples 41
4.5.1 LogoutRequest Example 41
4.5.2 LogoutResponse Example 42
4.5.3 LogoutRequest Example - Locally Initiated 43
4.5.4 LogoutResponse Example:Final Response to Locally Initiated Request 43
4.5.5 LogoutRequest Example with SAMLResponse and RelayState 43
4.5.6 LogoutResponse Example with SAMLRequest and RelayState 45
5 Security 46
5.1 Security Considerations for Implementers 46
5.2 Index of Security Parameters 46
6 Appendix A: Full WSDL 47
7 Appendix B: Product Behavior 48
8 Change Tracking 49
9 Index 50
1 Introduction
This document specifies the Security Assertion Markup Language (SAML) Proxy Request Signing Protocol, which allows proxy servers to perform operations that require knowledge of configured keys and other state information about federated sites known by the Security Token Service (STS) server.
Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1 Glossary
This document uses the following terms:
Active Directory Federation Services (AD FS) Proxy Server: An AD FS 2.0 service that processes SAML Federation Protocol messages. AD FS proxy servers are clients for the Security Assertion Markup Language (SAML) Proxy Request Signing Protocol (SAMLPR).
Active Directory Federation Services (AD FS) Security Token Service (STS): An AD FS 2.0 service that holds configuration information about federated sites. AD FS STS servers are servers for the Security Assertion Markup Language (SAML) Proxy Request Signing Protocol (SAMLPR).
certificate: A certificate is a collection of attributes and extensions that can be stored persistently. The set of attributes in a certificate can vary depending on the intended usage of the certificate. A certificate securely binds a public key to the entity that holds the corresponding private key. A certificate is commonly used for authentication and secure exchange of information on open networks, such as the Internet, extranets, and intranets. Certificates are digitally signed by the issuing certification authority (CA) and can be issued for a user, a computer, or a service. The most widely accepted format for certificates is defined by the ITU-T X.509 version 3 international standards. For more information about attributes and extensions, see [RFC3280] and [X509] sections 7 and 8.
SAML Artifact Binding: A method of transmitting SAML messages via references in HTTP messages, as specified in [SamlBinding] section 3.6.
SAML Identity Provider (IdP): A provider of SAML assertions, as specified in [SAMLCore2] section 2.
SAML Message: A SAML protocol message, as specified in [SAMLCore2] and [SamlBinding].
SAML Post Binding: A method of transmitting SAML messages via HTTP POST actions, as specified in [SamlBinding] section 3.5.
SAML Redirect Binding: A method of transmitting SAML messages via HTTP redirects, as specified in [SamlBinding] section 3.4.
SAML Service Provider (SP): A consumer of SAML assertions, as specified in [SAMLCore2] section 2.
Security Assertion Markup Language (SAML): The set of specifications that describe security assertions encoded in XML, profiles for attaching assertions to protocols and frameworks, request/response protocols used to obtain assertions, and the protocol bindings to transfer protocols, such as SOAP and HTTP.
security token service (STS): A web service that issues security tokens. That is, it makes assertions based on evidence that it trusts; these assertions are for consumption by whoever trusts it.
SHA-1 hash: A hashing algorithm as specified in [FIPS180-2] that was developed by the National Institute of Standards and Technology (NIST) and the National Security Agency (NSA).
SOAP: A lightweight protocol for exchanging structured information in a decentralized, distributed environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation-specific semantics. SOAP 1.2 supersedes SOAP 1.1. See [SOAP1.2-1/2003].
SOAP body: A container for the payload data being delivered by a SOAP message to its recipient. See [SOAP1.2-1/2007] section 5.3 for more information.
SOAP message: An XML document consisting of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. See [SOAP1.2-1/2007] section 5 for more information.
Uniform Resource Locator (URL): A string of characters in a standardized format that identifies a document or resource on the World Wide Web. The format is as specified in [RFC1738].
Web Services Description Language (WSDL): An XML format for describing network services as a set of endpoints that operate on messages that contain either document-oriented or procedure-oriented information. The operations and messages are described abstractly and are bound to a concrete network protocol and message format in order to define an endpoint. Related concrete endpoints are combined into abstract endpoints, which describe a network service. WSDL is extensible, which allows the description of endpoints and their messages regardless of the message formats or network protocols that are used.
XML namespace: A collection of names that is used to identify elements, types, and attributes in XML documents identified in a URI reference [RFC3986]. A combination of XML namespace and local name allows XML documents to use elements, types, and attributes that have the same names but come from different sources. For more information, see [XMLNS-2ED].
XML Schema (XSD): A language that defines the elements, attributes, namespaces, and data types for XML documents as defined by [XMLSCHEMA1/2] and [W3C-XSD] standards. An XML schema uses XML syntax for its language.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2 References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.