idnits 2.17.1 draft-campbell-oauth-saml-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 27, 2010) is 5015 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 B. Campbell, Ed. 3 Internet-Draft Ping Identity Corp. 4 Intended status: Standards Track C. Mortimore 5 Expires: January 28, 2011 Salesforce.com 6 July 27, 2010 8 SAML 2.0 Bearer Assertion Profile for OAuth 2.0 9 draft-campbell-oauth-saml-00 11 Abstract 13 This specification defines the use of a SAML 2.0 bearer assertion as 14 means for requesting an OAuth 2.0 access token. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 28, 2011. 33 Copyright Notice 35 Copyright (c) 2010 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 52 2. SAML Assertion Access Token Request . . . . . . . . . . . . . . 3 53 2.1. Client Requests Access Token . . . . . . . . . . . . . . . 4 54 2.2. Assertion Format and Processing Requirements . . . . . . . 5 55 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 6 56 2.4. Example (non-normative) . . . . . . . . . . . . . . . . . . 7 57 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 58 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 59 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 8 60 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 5.1. Normative References . . . . . . . . . . . . . . . . . . . 8 62 5.2. Informative References . . . . . . . . . . . . . . . . . . 9 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 65 1. Introduction 67 The Security Assertion Markup Language (SAML) 2.0 68 [OASIS.saml-core-2.0-os], is an XML-based framework that provides a 69 means for a subject to be identified across security domains. The 70 SAML specification, while primarily targeted at providing cross 71 domain web browser single sign-on, was also designed to be modular 72 and extensible to facilitate use in other contexts. The Assertion, 73 an XML security token, is a fundamental construct of SAML that is 74 most often adopted for use in other protocols and specifications. An 75 assertion is generally issued by an identity provider and consumed by 76 a service provider who relies on its content to identify the subject 77 for security related purposes. 79 OAuth 2.0 [I-D.ietf.oauth-v2] provides a method for making 80 authenticated HTTP requests to a resource using an access token. 81 Tokens are issued to third-party clients by an authorization server 82 with the (sometimes implicit) approval of the resource owner. OAuth 83 defines multiple profiles for obtaining access tokens to support a 84 wide range of client types and user experiences. One such method is 85 the use of an assertion which supports the case when a client wishes 86 to exchange an existing security token for an access token. However 87 the Oauth 2.0 leaves the specific format and validation of the 88 assertion out of scope. 90 This specification profiles the specific use of a SAML 2.0 bearer 91 assertion in requesting an access token using the assertion 92 grant_type from OAuth 2.0. The format and processing rules for the 93 SAML assertion defined in this specification are intentionally 94 similar to those in the Web Browser SSO Profile defined in 95 [OASIS.saml-profiles-2.0-os] with the goal of reusing, to the extent 96 reasonable, concepts and patterns from that well established profile. 98 1.1. Notational Conventions 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 102 document are to be interpreted as described in RFC 2119 [RFC2119]. 104 Unless otherwise noted, all the protocol parameter names and values 105 are case sensitive. 107 2. SAML Assertion Access Token Request 109 A SAML assertion is used to request an access token when a client 110 wishes to utilize an existing trust relationship, expressed though 111 the semantics of the SAML assertion, to establish authorization 112 without directly involving the resource owner's approval at the 113 resource server. 115 The process by which the client obtains the assertion is out of 116 scope. 118 +--------+ +---------------+ 119 | | | | 120 | |>--(A)-- SAML 2.0 Assertion ----->| Authorization | 121 | Client | | Server | 122 | |<--(B)---- Access Token ---------<| | 123 | | | | 124 +--------+ +---------------+ 126 Figure 1: Assertion Access Token Request 128 The request/response flow illustrated in Figure 1 includes the 129 following steps: 131 (A) The client sends an access token request to the authorization 132 server and includes a SAML 2.0 assertion. 134 (B) The authorization server validates the assertion per the 135 processing rules defined in this specification and issues an 136 access token. 138 2.1. Client Requests Access Token 140 The client requests an access token by making an HTTP "POST" request 141 to the token endpoint using an assertion as an access grant. The 142 client makes an access token request, as defined in the OAuth, with 143 the following parameter definitions taking precedence in the 144 constructed URI: 146 assertion_type 147 REQUIRED. The value of the assertion_format parameter MUST be 148 "http://oauth.net/assertion_type/saml/2.0/bearer" 150 assertion 151 REQUIRED. The value of the assertion parameter MUST contain a 152 single SAML 2.0 Assertion. The SAML assertion XML data MUST be 153 encoded using base64url, where the encoding adheres to the 154 definition in Section 5 of RFC4648 [RFC4648] and where the 155 padding bits set to zero. To to avoid the need for subsequent 156 encoding steps (by "application/x-www-form-urlencoded" 158 [W3C.REC-html401-19991224], for example), the base64url encoded 159 data SHOULD NOT be line wrapped and pad characters ("=") SHOULD 160 NOT be included. 162 2.2. Assertion Format and Processing Requirements 164 The authorization server MUST validate the assertion according to the 165 criteria below and, if valid, issues an access token response as 166 described in [I-D.ietf.oauth-v2]. The access token SHOULD be issued 167 only for the subject of the assertion 169 o The Assertion's element MUST contain a unique identifier 170 for the entity that issued the assertion; the Format attribute 171 MUST be omitted or have a value of 172 "urn:oasis:names:tc:SAML:2.0:nameid-format:entity". 174 o The assertion MUST contain a element that identifies the 175 resource owner for whom the access token is being requested. 177 o The element MUST contain a single 178 element and it MUST have a Method attribute with a value of 179 "urn:oasis:names:tc:SAML:2.0:cm:bearer". 181 o The element MUST contain a single 182 element. 184 o The element MUST have a Recipient 185 attribute with a value indicating the token endpoint URL of the 186 authorization server. The authorization server MUST verify that 187 the value of the Recipient attribute matches the token endpoint 188 URL (or an acceptable alias) to which the assertion was delivered. 190 o The element MUST have a NotOnOrAfter 191 attribute that limits the window during which the assertion can be 192 confirmed. The authorization server MUST verify that the 193 NotOnOrAfter instant has not passed, subject to allowable clock 194 skew between systems. 196 o The element MUST NOT contain a NotBefore 197 attribute. 199 o The element MAY also contain an Address 200 attribute limiting the client address from which the assertion can 201 be delivered. Verification of the Address is at the discretion of 202 the authorization server. 204 o If the assertion issuer authenticated the subject, the assertion 205 SHOULD contain a single representing that 206 authentication event. 208 o If the assertion was issued with the intention that the client act 209 autonomously on behalf of the subject, an SHOULD 210 NOT be included. 212 o Other statements, in particular, elements MAY 213 be included in the assertion. 215 o The assertion MUST contain an element with 216 an element containing a URI reference that identifies 217 the authorization server, or the service provider SAML entity of 218 its controlling domain, as an intended audience. The 219 authorization server MUST verify that it is an intended audience 220 for the assertion. 222 o The authorization server MAY ensure that bearer assertions are not 223 replayed, by maintaining the set of used ID values for the length 224 of time for which the assertion would be considered valid based on 225 the NotOnOrAfter attribute in the . 227 o The assertion MUST be digitally signed by the issuer and the 228 authorization server MUST verify the signature. 230 o Encrypted elements MAY appear in place of their plain text 231 counterparts as defined in [OASIS.saml-core-2.0-os]. 233 o The authorization server MUST verify that the assertion is valid 234 in all other respects per [OASIS.saml-core-2.0-os]. 236 2.3. Error Response 238 If the assertion is not valid, or its subject confirmation 239 requirements cannot be met, the the authorization server MUST 240 construct an error response as defined in [I-D.ietf.oauth-v2]. The 241 value of the error parameter MUST be the "invalid_grant" error code. 242 The authorization server MAY include additional information regarding 243 the reasons the assertion was considered invalid using the 244 error_description or error_uri parameters. 246 For example: 248 HTTP/1.1 400 Bad Request 249 Content-Type: application/json 250 Cache-Control: no-store 252 { 253 "error":"invalid_grant", 254 "error_description":"invalid signature" 255 } 257 2.4. Example (non-normative) 259 Though non-normative, the following examples illustrate what a 260 conformant assertion and access token request would look like. 262 Below is an example SAML 2.0 Assertion (whitespace formatting is for 263 display purposes only): 265 269 https://saml-idp.example.com 270 271 [...omitted for brevity...] 272 273 274 276 brian@example.com 277 278 280 283 284 285 286 287 https://saml-sp.example.net 288 289 290 291 Figure 2: Example SAML 2.0 Assertion 293 To present the assertion shown in the previous example as part of an 294 access token request, for example, the client makes the following 295 HTTPS request (line breaks are for display purposes only): 297 POST /token.oauth2 HTTP/1.1 298 Host: authz.example.net 299 Content-Type: application/x-www-form-urlencoded 301 grant_type=assertion&assertion_type=http%3A%2F%2Foauth.net%2Fasse 302 rtion_type%2Fsaml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZU 303 [...omitted for brevity...]b24-PC9Db25kaXRpb25zPjwvQXNzZXJ0aW9uPg 305 Figure 3: Example Request 307 3. Security Considerations 309 No additional considerations beyond those described within the OAuth 310 2.0 Protocol [I-D.ietf.oauth-v2] and in the Security and Privacy 311 Considerations for the OASIS Security Assertion Markup Language 312 (SAML) V2.0 [OASIS.saml-sec-consider-2.0-os]. 314 4. IANA Considerations 316 This document has no actions for IANA. 318 Appendix A. Contributors 320 The following people contributed wording and concepts to this 321 document: Patrick Harding, Peter Motyka, Peter Saint-Andre and David 322 Waite 324 5. References 326 5.1. Normative References 328 [I-D.ietf.oauth-v2] 329 Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 330 OAuth 2.0 Protocol", Jun 2010. 332 [OASIS.saml-core-2.0-os] 333 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 334 "Assertions and Protocol for the OASIS Security Assertion 335 Markup Language (SAML) V2.0", OASIS Standard saml-core- 336 2.0-os, March 2005. 338 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 339 Requirement Levels", BCP 14, RFC 2119, March 1997. 341 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 342 Encodings", RFC 4648, October 2006. 344 5.2. Informative References 346 [OASIS.saml-profiles-2.0-os] 347 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, 348 P., Philpott, R., and E. Maler, "Profiles for the OASIS 349 Security Assertion Markup Language (SAML) V2.0", OASIS 350 Standard OASIS.saml-profiles-2.0-os, March 2005. 352 [OASIS.saml-sec-consider-2.0-os] 353 Hirsch, F., Philpott, R., and E. Maler, "Security and 354 Privacy Considerations for the OASIS Security Markup 355 Language (SAML) V2.0", OASIS Standard saml-sec-consider- 356 2.0-os, March 2005. 358 [W3C.REC-html401-19991224] 359 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 360 Specification", World Wide Web Consortium 361 Recommendation REC-html401-19991224, December 1999, 362 . 364 Authors' Addresses 366 Brian Campbell (editor) 367 Ping Identity Corp. 369 Email: brian.d.campbell@gmail.com 371 Chuck Mortimore 372 Salesforce.com 374 Email: cmortimore@salesforce.com