From: http://www.ietf.org/internet-drafts/draft-campbell-oauth-saml-00.txt Title: SAML 2.0 Bearer Assertion Profile for OAuth 2.0 Reference: IETF Network Working Group, Internet Draft 'draft-campbell-oauth-saml-00' Date: July 27, 2010 Data Tracker: https://datatracker.ietf.org/doc/draft-campbell-oauth-saml/ Tracker Listing: http://ietfreport.isoc.org/idref/draft-campbell-oauth-saml/ Tools: http://tools.ietf.org/html/draft-campbell-oauth-saml-00 (HTML) Announced: http://www.ietf.org/mail-archive/web/i-d-announce/current/msg32476.html http://www.ietf.org/mail-archive/web/oauth/current/msg03875.html See also: IETF Open Authentication Protocol (OAuth) Working Group http://www.ietf.org/html.charters/oauth-charter.html IETF OAuth Working Group Status Pages http://tools.ietf.org/wg/oauth/ IETF OAuth Working Group Discussion List Archives http://www.ietf.org/mail-archive/web/oauth/current/maillist.html https://www.ietf.org/mailman/listinfo/oauth Bringing OAuth to the IETF (IETF Journal 5/1) http://xml.coverpages.org/newsletter/news2009-07-06.html#cite3 The OAuth Protocol: Authentication http://tools.ietf.org/html/draft-ietf-oauth-authentication The OAuth Protocol: Web Delegation http://tools.ietf.org/html/draft-ietf-oauth-web-delegation Evaluating OAUTH's Suitability for SIP Authentication http://tools.ietf.org/html/draft-beck-oauth-sip-eval Auth Access Tokens Using Credentials http://tools.ietf.org/html/draft-dehora-farrell-oauth-accesstoken-creds The OAuth 1.0 Protocol http://tools.ietf.org/html/draft-hammer-oauth OAuth Web Resource Authorization Profiles http://tools.ietf.org/html/draft-hardt-oauth Using OAuth for Recursive Delegation http://tools.ietf.org/html/draft-vrancken-oauth-redelegation ============================================================================== B. Campbell, Ed. Internet-Draft Ping Identity Corp. Intended status: Standards Track C. Mortimore Expires: January 28, 2011 Salesforce.com July 27, 2010 SAML 2.0 Bearer Assertion Profile for OAuth 2.0 draft-campbell-oauth-saml-00 Abstract This specification defines the use of a SAML 2.0 bearer assertion as means for requesting an OAuth 2.0 access token. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 28, 2011. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Campbell & Mortimore Expires January 28, 2011 [Page 1] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 2. SAML Assertion Access Token Request . . . . . . . . . . . . . . 3 2.1. Client Requests Access Token . . . . . . . . . . . . . . . 4 2.2. Assertion Format and Processing Requirements . . . . . . . 5 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Example (non-normative) . . . . . . . . . . . . . . . . . . 7 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 8 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1. Normative References . . . . . . . . . . . . . . . . . . . 8 5.2. Informative References . . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 Campbell & Mortimore Expires January 28, 2011 [Page 2] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 1. Introduction The Security Assertion Markup Language (SAML) 2.0 [OASIS.saml-core-2.0-os], is an XML-based framework that provides a means for a subject to be identified across security domains. The SAML specification, while primarily targeted at providing cross domain web browser single sign-on, was also designed to be modular and extensible to facilitate use in other contexts. The Assertion, an XML security token, is a fundamental construct of SAML that is most often adopted for use in other protocols and specifications. An assertion is generally issued by an identity provider and consumed by a service provider who relies on its content to identify the subject for security related purposes. OAuth 2.0 [I-D.ietf.oauth-v2] provides a method for making authenticated HTTP requests to a resource using an access token. Tokens are issued to third-party clients by an authorization server with the (sometimes implicit) approval of the resource owner. OAuth defines multiple profiles for obtaining access tokens to support a wide range of client types and user experiences. One such method is the use of an assertion which supports the case when a client wishes to exchange an existing security token for an access token. However the Oauth 2.0 leaves the specific format and validation of the assertion out of scope. This specification profiles the specific use of a SAML 2.0 bearer assertion in requesting an access token using the assertion grant_type from OAuth 2.0. The format and processing rules for the SAML assertion defined in this specification are intentionally similar to those in the Web Browser SSO Profile defined in [OASIS.saml-profiles-2.0-os] with the goal of reusing, to the extent reasonable, concepts and patterns from that well established profile. 1.1. Notational Conventions 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 RFC 2119 [RFC2119]. Unless otherwise noted, all the protocol parameter names and values are case sensitive. 2. SAML Assertion Access Token Request A SAML assertion is used to request an access token when a client wishes to utilize an existing trust relationship, expressed though the semantics of the SAML assertion, to establish authorization Campbell & Mortimore Expires January 28, 2011 [Page 3] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 without directly involving the resource owner's approval at the resource server. The process by which the client obtains the assertion is out of scope. +--------+ +---------------+ | | | | | |>--(A)-- SAML 2.0 Assertion ----->| Authorization | | Client | | Server | | |<--(B)---- Access Token ---------<| | | | | | +--------+ +---------------+ Figure 1: Assertion Access Token Request The request/response flow illustrated in Figure 1 includes the following steps: (A) The client sends an access token request to the authorization server and includes a SAML 2.0 assertion. (B) The authorization server validates the assertion per the processing rules defined in this specification and issues an access token. 2.1. Client Requests Access Token The client requests an access token by making an HTTP "POST" request to the token endpoint using an assertion as an access grant. The client makes an access token request, as defined in the OAuth, with the following parameter definitions taking precedence in the constructed URI: assertion_type REQUIRED. The value of the assertion_format parameter MUST be "http://oauth.net/assertion_type/saml/2.0/bearer" assertion REQUIRED. The value of the assertion parameter MUST contain a single SAML 2.0 Assertion. The SAML assertion XML data MUST be encoded using base64url, where the encoding adheres to the definition in Section 5 of RFC4648 [RFC4648] and where the padding bits set to zero. To to avoid the need for subsequent encoding steps (by "application/x-www-form-urlencoded" Campbell & Mortimore Expires January 28, 2011 [Page 4] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 [W3C.REC-html401-19991224], for example), the base64url encoded data SHOULD NOT be line wrapped and pad characters ("=") SHOULD NOT be included. 2.2. Assertion Format and Processing Requirements The authorization server MUST validate the assertion according to the criteria below and, if valid, issues an access token response as described in [I-D.ietf.oauth-v2]. The access token SHOULD be issued only for the subject of the assertion o The Assertion's element MUST contain a unique identifier for the entity that issued the assertion; the Format attribute MUST be omitted or have a value of "urn:oasis:names:tc:SAML:2.0:nameid-format:entity". o The assertion MUST contain a element that identifies the resource owner for whom the access token is being requested. o The element MUST contain a single element and it MUST have a Method attribute with a value of "urn:oasis:names:tc:SAML:2.0:cm:bearer". o The element MUST contain a single element. o The element MUST have a Recipient attribute with a value indicating the token endpoint URL of the authorization server. The authorization server MUST verify that the value of the Recipient attribute matches the token endpoint URL (or an acceptable alias) to which the assertion was delivered. o The element MUST have a NotOnOrAfter attribute that limits the window during which the assertion can be confirmed. The authorization server MUST verify that the NotOnOrAfter instant has not passed, subject to allowable clock skew between systems. o The element MUST NOT contain a NotBefore attribute. o The element MAY also contain an Address attribute limiting the client address from which the assertion can be delivered. Verification of the Address is at the discretion of the authorization server. o If the assertion issuer authenticated the subject, the assertion SHOULD contain a single representing that Campbell & Mortimore Expires January 28, 2011 [Page 5] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 authentication event. o If the assertion was issued with the intention that the client act autonomously on behalf of the subject, an SHOULD NOT be included. o Other statements, in particular, elements MAY be included in the assertion. o The assertion MUST contain an element with an element containing a URI reference that identifies the authorization server, or the service provider SAML entity of its controlling domain, as an intended audience. The authorization server MUST verify that it is an intended audience for the assertion. o The authorization server MAY ensure that bearer assertions are not replayed, by maintaining the set of used ID values for the length of time for which the assertion would be considered valid based on the NotOnOrAfter attribute in the . o The assertion MUST be digitally signed by the issuer and the authorization server MUST verify the signature. o Encrypted elements MAY appear in place of their plain text counterparts as defined in [OASIS.saml-core-2.0-os]. o The authorization server MUST verify that the assertion is valid in all other respects per [OASIS.saml-core-2.0-os]. 2.3. Error Response If the assertion is not valid, or its subject confirmation requirements cannot be met, the the authorization server MUST construct an error response as defined in [I-D.ietf.oauth-v2]. The value of the error parameter MUST be the "invalid_grant" error code. The authorization server MAY include additional information regarding the reasons the assertion was considered invalid using the error_description or error_uri parameters. Campbell & Mortimore Expires January 28, 2011 [Page 6] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 For example: HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_grant", "error_description":"invalid signature" } 2.4. Example (non-normative) Though non-normative, the following examples illustrate what a conformant assertion and access token request would look like. Below is an example SAML 2.0 Assertion (whitespace formatting is for display purposes only): https://saml-idp.example.com [...omitted for brevity...] brian@example.com https://saml-sp.example.net Campbell & Mortimore Expires January 28, 2011 [Page 7] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 Figure 2: Example SAML 2.0 Assertion To present the assertion shown in the previous example as part of an access token request, for example, the client makes the following HTTPS request (line breaks are for display purposes only): POST /token.oauth2 HTTP/1.1 Host: authz.example.net Content-Type: application/x-www-form-urlencoded grant_type=assertion&assertion_type=http%3A%2F%2Foauth.net%2Fasse rtion_type%2Fsaml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZU [...omitted for brevity...]b24-PC9Db25kaXRpb25zPjwvQXNzZXJ0aW9uPg Figure 3: Example Request 3. Security Considerations No additional considerations beyond those described within the OAuth 2.0 Protocol [I-D.ietf.oauth-v2] and in the Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0 [OASIS.saml-sec-consider-2.0-os]. 4. IANA Considerations This document has no actions for IANA. Appendix A. Contributors The following people contributed wording and concepts to this document: Patrick Harding, Peter Motyka, Peter Saint-Andre and David Waite 5. References 5.1. Normative References [I-D.ietf.oauth-v2] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The OAuth 2.0 Protocol", Jun 2010. [OASIS.saml-core-2.0-os] Cantor, S., Kemp, J., Philpott, R., and E. Maler, Campbell & Mortimore Expires January 28, 2011 [Page 8] Internet-Draft OAuth SAML Bearer Assertion Profile July 2010 "Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0", OASIS Standard saml-core- 2.0-os, March 2005. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. 5.2. Informative References [OASIS.saml-profiles-2.0-os] Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, "Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", OASIS Standard OASIS.saml-profiles-2.0-os, March 2005. [OASIS.saml-sec-consider-2.0-os] Hirsch, F., Philpott, R., and E. Maler, "Security and Privacy Considerations for the OASIS Security Markup Language (SAML) V2.0", OASIS Standard saml-sec-consider- 2.0-os, March 2005. [W3C.REC-html401-19991224] Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Specification", World Wide Web Consortium Recommendation REC-html401-19991224, December 1999, . Authors' Addresses Brian Campbell (editor) Ping Identity Corp. Email: brian.d.campbell@gmail.com Chuck Mortimore Salesforce.com Email: cmortimore@salesforce.com Campbell & Mortimore Expires January 28, 2011 [Page 9]