idnits 2.17.1 draft-ietf-oauth-saml2-bearer-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 (December 16, 2010) is 4878 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: June 19, 2011 Salesforce.com 6 December 16, 2010 8 SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0 9 draft-ietf-oauth-saml2-bearer-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 June 19, 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 . . . . . . . . . . . . . . . . . . . 9 58 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 59 4.1. Parameter Registration Request . . . . . . . . . . . . . . 9 60 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 9 61 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 62 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 5.1. Normative References . . . . . . . . . . . . . . . . . . . 11 64 5.2. Informative References . . . . . . . . . . . . . . . . . . 11 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 67 1. Introduction 69 The Security Assertion Markup Language (SAML) 2.0 70 [OASIS.saml-core-2.0-os], is an XML-based framework that allows for 71 identity and security information to be shared across security 72 domains. The SAML specification, while primarily targeted at 73 providing cross domain web browser single sign-on, was also designed 74 to be modular and extensible to facilitate use in other contexts. 75 The Assertion, an XML security token, is a fundamental construct of 76 SAML that is often adopted for use in other protocols and 77 specifications. An Assertion is generally issued by an identity 78 provider and consumed by a service provider who relies on its content 79 to identify the Assertion's subject for security related purposes. 81 The OAuth 2.0 Protocol Framework [I-D.ietf.oauth-v2] provides a 82 method for making authenticated HTTP requests to a resource using an 83 access token. Access tokens are issued to third-party clients by an 84 authorization server (AS) with the (sometimes implicit) approval of 85 the resource owner. OAuth defines multiple profiles for obtaining 86 access tokens to support a wide range of client types and user 87 experiences. One such method is one in which the client trades an 88 'assertion' (not specifically a SAML Assertion) for an access token 89 using the so-called 'assertion grant_type'. However OAuth 2.0 leaves 90 the specific format and validation of the assertion out of scope. 92 This specification profiles the use of a SAML 2.0 bearer Assertion in 93 requesting an access token using the assertion grant_type from OAuth 94 2.0. The format and processing rules for the SAML Assertion defined 95 in this specification are intentionally similar, though not 96 identical, to those in the Web Browser SSO Profile defined in 97 [OASIS.saml-profiles-2.0-os] reusing, to the extent reasonable, 98 concepts and patterns from that well-established profile. 100 1.1. Notational Conventions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in RFC 2119 [RFC2119]. 106 Unless otherwise noted, all the protocol parameter names and values 107 are case sensitive. 109 2. SAML Assertion Access Token Request 111 A SAML Assertion can be used to request an access token when a client 112 wishes to utilize an existing trust relationship, expressed though 113 the semantics of (and digital signature calculated over) the SAML 114 Assertion, without a direct user approval step at the authorization 115 server. 117 The process by which the client obtains the SAML Assertion, prior to 118 exchanging it with the authorization server, is out of scope. 120 +--------+ +---------------+ 121 | | | | 122 | |>--(A)-- SAML 2.0 Assertion ----->| Authorization | 123 | Client | | Server | 124 | |<--(B)---- Access Token ---------<| | 125 | | | | 126 +--------+ +---------------+ 128 Figure 1: Assertion Access Token Request 130 The request/response flow illustrated in Figure 1 includes the 131 following steps: 133 (A) The client sends an access token request to the authorization 134 server with an appropriate OAuth grant_type and includes a SAML 135 2.0 Assertion. 137 (B) The authorization server validates the Assertion per the 138 processing rules defined in this specification and issues an 139 access token. 141 2.1. Client Requests Access Token 143 The client includes the Assertion in the access token request, the 144 core details of which are defined in OAuth [I-D.ietf.oauth-v2], by 145 specifying "http://oauth.net/grant_type/assertion/saml/2.0/bearer" as 146 the absolute URI value of the "grant_type" parameter and by adding 147 the following parameter: 149 assertion 150 REQUIRED. The value of the assertion parameter MUST contain a 151 single SAML 2.0 Assertion. The SAML Assertion XML data MUST be 152 encoded using base64url, where the encoding adheres to the 153 definition in Section 5 of RFC4648 [RFC4648] and where the 154 padding bits are set to zero. To to avoid the need for 155 subsequent encoding steps (by "application/ 156 x-www-form-urlencoded" [W3C.REC-html401-19991224], for 157 example), the base64url encoded data SHOULD NOT be line wrapped 158 and pad characters ("=") SHOULD NOT be included. 160 Authorization servers SHOULD issue access tokens with a limited 161 lifetime and require clients to refresh them by requesting a new 162 access token using the same assertion, if it is still valid, or with 163 a new assertion. The authorization server SHOULD NOT issue a refresh 164 token. 166 2.2. Assertion Format and Processing Requirements 168 Prior to issuing an access token response as described in 169 [I-D.ietf.oauth-v2], the authorization server MUST validate the 170 Assertion according to the criteria below. If present, the 171 authorization server MUST also validate the client credentials. 172 Application of additional restrictions and policy are at the 173 discretion of the authorization server. 175 o The Assertion's element MUST contain a unique identifier 176 for the entity that issued the Assertion; the Format attribute 177 MUST be omitted or have a value of 178 "urn:oasis:names:tc:SAML:2.0:nameid-format:entity". 180 o The Assertion MUST contain a element. The subject MAY 181 identify the resource owner for whom the access token is being 182 requested. 184 o The element MUST contain at least one 185 element that allows the authorization server 186 to confirm it as a bearer Assertion. Conditions for bearer 187 subject confirmation are described below. 189 * The MUST have a Method attribute with a 190 value of "urn:oasis:names:tc:SAML:2.0:cm:bearer" and MUST 191 contain a element. 193 * The element MUST have a Recipient 194 attribute with a value indicating the token endpoint URL of the 195 authorization server. The authorization server MUST verify 196 that the value of the Recipient attribute matches the token 197 endpoint URL (or an acceptable alias) to which the Assertion 198 was delivered. 200 * The element MUST have a NotOnOrAfter 201 attribute that limits the window during which the Assertion can 202 be confirmed. The authorization server MUST verify that the 203 NotOnOrAfter instant has not passed, subject to allowable clock 204 skew between systems. The authorization server MAY ensure that 205 bearer Assertions are not replayed, by maintaining the set of 206 used ID values for the length of time for which the Assertion 207 would be considered valid based on the NotOnOrAfter attribute 208 in the . 210 * The element MAY also contain an 211 Address attribute limiting the client address from which the 212 Assertion can be delivered. Verification of the Address is at 213 the discretion of the authorization server. 215 o If the Assertion issuer authenticated the subject, the Assertion 216 SHOULD contain a single representing that 217 authentication event. 219 o If the Assertion was issued with the intention that the client act 220 autonomously on behalf of the subject, an SHOULD 221 NOT be included. The client SHOULD be identified in the 222 or similar element the element or by other 223 available means like [OASIS.saml-deleg-cs]. 225 o Other statements, in particular, elements MAY 226 be included in the Assertion. 228 o The Assertion MUST contain an element with 229 an element containing a URI reference that identifies 230 the authorization server, or the service provider SAML entity of 231 its controlling domain, as an intended audience. The 232 authorization server MUST verify that it is an intended audience 233 for the Assertion. 235 o The Assertion MUST be digitally signed by the issuer and the 236 authorization server MUST verify the signature. 238 o Encrypted elements MAY appear in place of their plain text 239 counterparts as defined in [OASIS.saml-core-2.0-os]. 241 o The authorization server MUST verify that the Assertion is valid 242 in all other respects per [OASIS.saml-core-2.0-os] such as (but 243 not limited to) evaluating all content within the Conditions 244 element including the NotOnOrAfter and NotBefore attributes, 245 rejecting unknown condition types, etc. 247 2.3. Error Response 249 If the Assertion is not valid, or its subject confirmation 250 requirements cannot be met, the the authorization server MUST 251 construct an error response as defined in [I-D.ietf.oauth-v2]. The 252 value of the error parameter MUST be the "invalid_grant" error code. 253 The authorization server MAY include additional information regarding 254 the reasons the Assertion was considered invalid using the 255 error_description or error_uri parameters. 257 For example: 259 HTTP/1.1 400 Bad Request 260 Content-Type: application/json 261 Cache-Control: no-store 263 { 264 "error":"invalid_grant", 265 "error_description":"Audience validation failed" 266 } 268 2.4. Example (non-normative) 270 Though non-normative, the following examples illustrate what a 271 conforming Assertion and access token request would look like. 273 Below is an example SAML 2.0 Assertion (whitespace formatting is for 274 display purposes only): 276 280 https://saml-idp.example.com 281 282 [...omitted for brevity...] 283 284 285 287 brian@example.com 288 289 291 294 295 296 297 298 https://saml-sp.example.net 299 300 301 302 303 304 urn:oasis:names:tc:SAML:2.0:ac:classes:X509 305 306 307 308 310 Figure 2: Example SAML 2.0 Assertion 312 To present the Assertion shown in the previous example as part of an 313 access token request, for example, the client might make the 314 following HTTPS request (line breaks are for display purposes only): 316 POST /token.oauth2 HTTP/1.1 317 Host: authz.example.net 318 Content-Type: application/x-www-form-urlencoded 320 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F 321 saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ 322 [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 324 Figure 3: Example Request 326 3. Security Considerations 328 No additional considerations beyond those described within the OAuth 329 2.0 Protocol Framework [I-D.ietf.oauth-v2] and in the Security and 330 Privacy Considerations for the OASIS Security Assertion Markup 331 Language (SAML) V2.0 [OASIS.saml-sec-consider-2.0-os]. 333 4. IANA Considerations 335 4.1. Parameter Registration Request 337 The following is the parameter registration request, as defined in 338 The OAuth Parameters Registry of The OAuth 2.0 Protocol Framework 339 [I-D.ietf.oauth-v2], for the "assertion" parameter: 341 Parameter name: assertion 343 Parameter usage location: The token endpoint request. 345 Change controller: IETF 347 Specification document(s): draft-ietf-oauth-saml2-bearer 349 Related information: None 351 Appendix A. Contributors 353 The following people contributed wording and concepts to this 354 document: Paul Madsen, Patrick Harding, Peter Motyka, Eran Hammer- 355 Lahav, Peter Saint-Andre, Ian Barnett, Eric Fazendin, Torsten 356 Lodderstedt, Scott Cantor and David Waite 358 Appendix B. Document History 360 [[ to be removed by RFC editor before publication as an RFC ]] 362 draft-campbell-oauth-saml-00 364 o Added Parameter Registration Request for "assertion" to IANA 365 Considerations. 367 o Changed document name to draft-ietf-oauth-saml2-bearer in 368 anticipation of becoming a OAUTH WG item. 370 o Attempt to move the entire definition of the 'assertion' parameter 371 into this draft (it will no longer be defined in OAuth 2 Protocol 372 Framework). 374 draft-campbell-oauth-saml-01 376 o Updated to reference draft-ietf-oauth-v2-11 and reflect changes 377 from -10 to -11. 379 o Updated examples. 381 o Relaxed processing rules to allow for more than one 382 SubjectConfirmation element. 384 o Removed the 'MUST NOT contain a NotBefore attribute' on 385 SubjectConfirmationData. 387 o Relaxed wording that ties the subject of the Assertion to the 388 resource owner. 390 o Added some wording about identifying the client when the subject 391 hasn't directly authenticated including an informative reference 392 to SAML V2.0 Condition for Delegation Restriction. 394 o Added a few examples to the language about verifying that the 395 Assertion is valid in all other respects. 397 o Added some wording to the introduction about the similarities to 398 Web SSO in the format and processing rules 400 o Changed the grant_type (was assertion_type) URI from 401 http://oauth.net/assertion_type/saml/2.0/bearer to 402 http://oauth.net/grant_type/assertion/saml/2.0/bearer 404 o Changed title to include "Grant Type" in it. 406 o Editorial updates based on feedback from the WG and others 407 (including capitalization of Assertion when referring to SAML). 409 draft-campbell-oauth-saml-00 411 o Initial I-D 413 5. References 415 5.1. Normative References 417 [I-D.ietf.oauth-v2] 418 Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 419 OAuth 2.0 Protocol Framework", ID draft-ietf-oauth-v2-11, 420 Dec 2010. 422 [OASIS.saml-core-2.0-os] 423 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 424 "Assertions and Protocol for the OASIS Security Assertion 425 Markup Language (SAML) V2.0", OASIS Standard saml-core- 426 2.0-os, March 2005. 428 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 429 Requirement Levels", BCP 14, RFC 2119, March 1997. 431 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 432 Encodings", RFC 4648, October 2006. 434 5.2. Informative References 436 [OASIS.saml-deleg-cs] 437 Cantor, S., Ed., "SAML V2.0 Condition for Delegation 438 Restriction", Nov 2009. 440 [OASIS.saml-profiles-2.0-os] 441 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, 442 P., Philpott, R., and E. Maler, "Profiles for the OASIS 443 Security Assertion Markup Language (SAML) V2.0", OASIS 444 Standard OASIS.saml-profiles-2.0-os, March 2005. 446 [OASIS.saml-sec-consider-2.0-os] 447 Hirsch, F., Philpott, R., and E. Maler, "Security and 448 Privacy Considerations for the OASIS Security Markup 449 Language (SAML) V2.0", OASIS Standard saml-sec-consider- 450 2.0-os, March 2005. 452 [W3C.REC-html401-19991224] 453 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 454 Specification", World Wide Web Consortium 455 Recommendation REC-html401-19991224, December 1999, 456 . 458 Authors' Addresses 460 Brian Campbell (editor) 461 Ping Identity Corp. 463 Email: brian.d.campbell@gmail.com 465 Chuck Mortimore 466 Salesforce.com 468 Email: cmortimore@salesforce.com