idnits 2.17.1 draft-ietf-oauth-assertions-10.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 (January 19, 2013) is 4108 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) == Outdated reference: A later version (-09) exists of draft-iab-privacy-considerations-03 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-jwt-bearer-04 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-15 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group B. Campbell 3 Internet-Draft Ping 4 Intended status: Standards Track C. Mortimore 5 Expires: July 23, 2013 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 January 19, 2013 11 Assertion Framework for OAuth 2.0 12 draft-ietf-oauth-assertions-10 14 Abstract 16 This specification provides a framework for the use of assertions 17 with OAuth 2.0 in the form of a new client authentication mechanism 18 and a new authorization grant type. Mechanisms are specified for 19 transporting assertions during interactions with a token endpoint, as 20 well as general processing rules. 22 The intent of this specification is to provide a common framework for 23 OAuth 2.0 to interwork with other identity systems using assertions, 24 and to provide alternative client authentication mechanisms. 26 Note that this specification only defines abstract message flows and 27 processing rules. In order to be implementable, companion 28 specifications are necessary to provide the corresponding concrete 29 instantiations. 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on July 23, 2013. 48 Copyright Notice 49 Copyright (c) 2013 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Interoperability Considerations . . . . . . . . . . . . . 4 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 8 69 4.1. Using Assertions as Authorization Grants . . . . . . . . . 8 70 4.1.1. Error Responses . . . . . . . . . . . . . . . . . . . 9 71 4.2. Using Assertions for Client Authentication . . . . . . . . 9 72 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 10 73 5. Assertion Content and Processing . . . . . . . . . . . . . . . 11 74 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 11 75 5.2. General Assertion Format and Processing Rules . . . . . . 12 76 6. Specific Assertion Format and Processing Rules . . . . . . . . 13 77 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 13 78 6.2. Client Acting on Behalf of Itself . . . . . . . . . . . . 14 79 6.3. Client Acting on Behalf of a User . . . . . . . . . . . . 15 80 6.4. Client Acting on Behalf of an Anonymous User . . . . . . . 16 81 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 82 7.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . . 17 83 7.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . . 17 84 7.3. Unauthorized Disclosure of Personal Information . . . . . 18 85 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 86 8.1. assertion Parameter Registration . . . . . . . . . . . . . 19 87 8.2. client_assertion Parameter Registration . . . . . . . . . 19 88 8.3. client_assertion_type Parameter Registration . . . . . . . 19 89 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 90 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 91 9.2. Informative References . . . . . . . . . . . . . . . . . . 20 92 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 20 93 Appendix B. Document History . . . . . . . . . . . . . . . . . . 20 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 96 1. Introduction 98 OAuth 2.0 [RFC6749] is an authorization framework that enables a 99 third-party application to obtain limited access to a protected HTTP 100 resource. In OAuth, those third-party applications are called 101 clients; they access protected resources by presenting an access 102 token to the HTTP resource. Access tokens are issued to clients by 103 an authorization server with the (sometimes implicit) approval of the 104 resource owner. These access tokens are typically obtained by 105 exchanging an authorization grant, which represents the authorization 106 granted by the resource owner (or by a privileged administrator). 107 Several authorization grant types are defined to support a wide range 108 of client types and user experiences. OAuth also provides an 109 extensibility mechanism for defining additional grant types, which 110 can serve as a bridge between OAuth and other protocol frameworks. 112 This specification provides a general framework for the use of 113 assertions as authorization grants with OAuth 2.0. It also provides 114 a framework for assertions to be used for client authentication. It 115 provides generic mechanisms for transporting assertions during 116 interactions with an authorization server's token endpoint, as well 117 as general rules for the content and processing of those assertions. 118 The intent is to provide an alternative client authentication 119 mechanism (one that doesn't send client secrets), as well as to 120 facilitate the use of OAuth 2.0 in client-server integration 121 scenarios, where the end-user may not be present. 123 This specification only defines abstract message flows and processing 124 rules. In order to be implementable, companion specifications are 125 necessary to provide the corresponding concrete instantiations. For 126 instance, SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 127 [I-D.ietf-oauth-saml2-bearer] defines a concrete instantiation for 128 SAML 2.0 tokens and JSON Web Token (JWT) Bearer Token Profiles for 129 OAuth 2.0 [I-D.ietf-oauth-jwt-bearer] defines a concrete 130 instantiation for JWT tokens. 132 Note: The use of assertions for client authentication is orthogonal 133 to and separable from using assertions as an authorization grant. 134 They can be used either in combination or separately. Client 135 assertion authentication is nothing more than an alternative way for 136 a client to authenticate to the token endpoint and must be used in 137 conjunction with some grant type to form a complete and meaningful 138 protocol request. Assertion authorization grants may be used with or 139 without client authentication or identification. Whether or not 140 client authentication is needed in conjunction with an assertion 141 authorization grant, as well as the supported types of client 142 authentication, are policy decisions at the discretion of the 143 authorization server. 145 1.1. Interoperability Considerations 147 This specification defines a framework for using assertions with 148 OAuth 2.0. However, as an abstract framework in which the data 149 formats used for representing many values are not defined, on its 150 own, this specification is not sufficient to produce interoperable 151 implementations. 153 Two other specifications that profile this framework for specific 154 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 155 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 156 uses JSON Web Tokens (JWTs). These two instantiations of this 157 framework specify additional details about the assertion encoding and 158 processing rules for using those kinds of assertions with OAuth 2.0. 160 However, even when profiled for specific assertion types, additional 161 profiling for specific use cases will be required to achieve full 162 interoperability. Deployments for particular trust frameworks, 163 circles of trust, or other uses cases will need to agree among the 164 participants on the kinds of values to be used for some abstract 165 fields defined by this specification. For example the values of 166 Issuer, Subject, and Audience fields might be URLs, URIs, fully 167 qualified domain names, OAuth client IDs, IP addresses, or other 168 values, depending upon the requirements of the particular use case. 169 The verification rules for some values will also be use case 170 specific. 172 This framework was designed with the clear expectation that 173 additional specifications will define prescriptive profiles and 174 extensions necessary to achieve full web-scale interoperability for 175 particular use cases. 177 2. Terminology 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 181 document are to be interpreted as described in [RFC2119] . 183 Throughout this document, values are quoted to indicate that they are 184 to be taken literally. When using these values in protocol messages, 185 the quotes must not be used as part of the value. 187 3. Framework 189 An assertion is a package of information that allows identity and 190 security information to be shared across security domains. An 191 assertion typically contains information about a subject or 192 principal, information about the party that issued the assertion and 193 when was it issued, as well as the conditions under which the 194 assertion is to be considered valid, such as when and where it can be 195 used. 197 The entity that creates and signs the assertion is typically known as 198 the "Issuer" and the entity that consumes the assertion and relies on 199 its information is typically known as the "Relying Party". In the 200 context of this document, the authorization server acts as a relying 201 party. 203 Assertions used in the protocol exchanges defined by this 204 specification MUST always be protected against tampering using a 205 digital signature or a keyed message digest applied by the issuer. 206 An assertion MAY additionally be encrypted, preventing unauthorized 207 parties from inspecting the content. 209 Although this document does not define the processes by which the 210 client obtains the assertion (prior to sending it to the 211 authorization server), there are two common patterns described below. 213 In the first pattern, depicted in Figure 1, the client obtains an 214 assertion from a third party entity capable of issuing, renewing, 215 transforming, and validating security tokens. Typically such an 216 entity is known as a "Security Token Service" (STS) or just "Token 217 Service" and a trust relationship (usually manifested in the exchange 218 of some kind of key material) exists between the token service and 219 the relying party. The token service is the assertion issuer; its 220 role is to fulfill requests from clients, which present various 221 credentials, and mint assertions as requested, fill them with 222 appropriate information, and sign them. WS-Trust [OASIS.WS-Trust] is 223 one available standard for requesting security tokens (assertions). 225 Relying 226 Party Client Token Service 227 | | | 228 | | 1) Request Assertion | 229 | |------------------------>| 230 | | | 231 | | 2) Assertion | 232 | |<------------------------| 233 | 3) Assertion | | 234 |<-------------------------| | 235 | | | 236 | 4) OK or Failure | | 237 |------------------------->| | 238 | | | 239 | | | 241 Figure 1: Third Party Created Assertion 243 In the second pattern, depicted in Figure 2, the client creates 244 assertions locally. To sign the assertions, it has to obtain key 245 material: either symmetric keys or asymmetric key pairs. The 246 mechanisms for obtaining this key material are beyond the scope of 247 this specification. 249 Although assertions are usually used to convey identity and security 250 information, self-issued assertions can also serve a different 251 purpose. They can be used to demonstrate knowledge of some secret, 252 such as a client secret, without actually communicating the secret 253 directly in the transaction. In that case, additional information 254 included in the assertion by the client itself will be of limited 255 value to the relying party and, for this reason, only a bare minimum 256 of information is typically included in such an assertion, such as 257 information about issuing and usage conditions. 259 Relying 260 Party Client 261 | | 262 | | 1) Create 263 | | Assertion 264 | |--------------+ 265 | | | 266 | | 2) Assertion | 267 | |<-------------+ 268 | 3) Assertion | 269 |<-------------------------| 270 | | 271 | 4) OK or Failure | 272 |------------------------->| 273 | | 274 | | 276 Figure 2: Self-Issued Assertion 278 Deployments need to determine the appropriate variant to use based on 279 the required level of security, the trust relationship between the 280 entities, and other factors. 282 From the perspective of what must be done by the entity presenting 283 the assertion, there are two general types of assertions: 285 1. Bearer Assertions: Any entity in possession of a bearer assertion 286 (e.g. the bearer) can use it to get access to the associated 287 resources (without demonstrating possession of a cryptographic 288 key). To prevent misuse, bearer assertions need to be protected 289 from disclosure in storage and in transport. A secure 290 communication channel is required between all entities to avoid 291 leaking the assertion to unauthorized parties. 293 2. Holder-of-Key Assertions: To access the associated resources, the 294 entity presenting the assertion must demonstrate possession of 295 additional cryptographic material. The token service thereby 296 binds a key identifier to the assertion and the client has to 297 demonstrate to the relying party that it knows the key 298 corresponding to that identifier when presenting the assertion. 299 This mechanism provides additional security properties. 301 The protocol parameters and processing rules defined in this document 302 are intended to support a client presenting a bearer assertion to an 303 authorization server. The use of holder-of-key assertions are not 304 precluded by this document, but additional protocol details would 305 need to be specified. 307 4. Transporting Assertions 309 This section defines HTTP parameters for transporting assertions 310 during interactions with a token endpoint of an OAuth authorization 311 server. Because requests to the token endpoint result in the 312 transmission of clear-text credentials (in both the HTTP request and 313 response), all requests to the token endpoint MUST use TLS, as 314 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 316 4.1. Using Assertions as Authorization Grants 318 This section defines the use of assertions as authorization grants, 319 based on the definition provided in Section 4.5 of OAuth 2.0 320 [RFC6749]. When using assertions as authorization grants, the client 321 includes the assertion and related information using the following 322 HTTP request parameters: 324 grant_type REQUIRED. The format of the assertion as defined by the 325 authorization server. The value MUST be an absolute URI. 327 assertion REQUIRED. The assertion being used as an authorization 328 grant. Specific serialization of the assertion is defined by 329 profile documents. The serialization MUST be encoded for 330 transport within HTTP forms. It is RECOMMENDED that base64url be 331 used. 333 scope OPTIONAL. The requested scope as described in Section 3.3 of 334 OAuth 2.0 [RFC6749]. When exchanging assertions for access 335 tokens, the authorization for the token has been previously 336 granted through some out-of-band mechanism. As such, the 337 requested scope MUST be equal or lesser than the scope originally 338 granted to the authorized accessor. If the scope parameter and/or 339 value are omitted, the scope MUST be treated as equal to the scope 340 originally granted to the authorized accessor. The Authorization 341 Server MUST limit the scope of the issued access token to be equal 342 or lesser than the scope originally granted to the authorized 343 accessor. 345 The following non-normative example demonstrates an assertion being 346 used as an authorization grant (with extra line breaks for display 347 purposes only): 349 POST /token HTTP/1.1 350 Host: server.example.com 351 Content-Type: application/x-www-form-urlencoded 353 client_id=s6BhdRkqt3& 354 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 355 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 357 An assertion used in this context is generally a short lived 358 representation of the authorization grant and authorization servers 359 SHOULD NOT issue access tokens with a lifetime that exceeds the 360 validity period of the assertion by a significant period. In 361 practice, that will usually mean that refresh tokens are not issued 362 in response to assertion grant requests and access tokens will be 363 issued with a reasonably short lifetime. Clients can refresh an 364 expired access token by requesting a new one using the same 365 assertion, if it is still valid, or with a new assertion. 367 An IETF URN for use as the "grant_type" value can be requested using 368 the template in [RFC6755]. A URN of the form 369 urn:ietf:params:oauth:grant-type:* is suggested. 371 4.1.1. Error Responses 373 If an assertion is not valid or has expired, the Authorization Server 374 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 375 The value of the "error" parameter MUST be the "invalid_grant" error 376 code. The authorization server MAY include additional information 377 regarding the reasons the assertion was considered invalid using the 378 "error_description" or "error_uri" parameters. 380 For example: 382 HTTP/1.1 400 Bad Request 383 Content-Type: application/json 384 Cache-Control: no-store 386 { 387 "error":"invalid_grant", 388 "error_description":"Audience validation failed" 389 } 391 4.2. Using Assertions for Client Authentication 393 The following section defines the use of assertions as client 394 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 395 When using assertions as client credentials, the client includes the 396 assertion and related information using the following HTTP request 397 parameters: 399 client_id OPTIONAL. The client identifier as described in Section 400 2.2 of OAuth 2.0 [RFC6749]. When present, the "client_id" MUST 401 identify the client to the authorization server. 403 client_assertion_type REQUIRED. The format of the assertion as 404 defined by the authorization server. The value MUST be an 405 absolute URI. 407 client_assertion REQUIRED. The assertion being used to authenticate 408 the client. Specific serialization of the assertion is defined by 409 profile documents. The serialization MUST be encoded for 410 transport within HTTP forms. It is RECOMMENDED that base64url be 411 used. 413 The following non-normative example demonstrates a client 414 authenticating using an assertion during an Access Token Request, as 415 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 416 breaks for display purposes only): 418 POST /token HTTP/1.1 419 Host: server.example.com 420 Content-Type: application/x-www-form-urlencoded 422 grant_type=authorization_code& 423 code=i1WsRn1uB1& 424 client_id=s6BhdRkqt3& 425 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 426 %3Aclient-assertion-type%3Asaml2-bearer& 427 client_assertion=PHNhbW...[omitted for brevity]...ZT 429 Token endpoints can differentiate between assertion based credentials 430 and other client credential types by looking for the presence of the 431 "client_assertion" and "client_assertion_type" parameters, which will 432 only be present when using assertions for client authentication. 434 An IETF URN for use as the "client_assertion_type" value may be 435 requested using the template in [RFC6755]. A URN of the form 436 urn:ietf:params:oauth:client-assertion-type:* is suggested. 438 4.2.1. Error Responses 440 If an assertion is invalid for any reason or if more than one client 441 authentication mechanism is used, the Authorization Server MUST 442 construct an error response as defined in OAuth 2.0 [RFC6749]. The 443 value of the "error" parameter MUST be the "invalid_client" error 444 code. The authorization server MAY include additional information 445 regarding the reasons the client assertion was considered invalid 446 using the "error_description" or "error_uri" parameters. 448 For example: 450 HTTP/1.1 400 Bad Request 451 Content-Type: application/json 452 Cache-Control: no-store 454 { 455 "error":"invalid_client" 456 "error_description":"assertion has expired" 457 } 459 5. Assertion Content and Processing 461 This section provides a general content and processing model for the 462 use of assertions in OAuth 2.0 [RFC6749]. 464 5.1. Assertion Metamodel 466 The following are entities and metadata involved in the issuance, 467 exchange, and processing of assertions in OAuth 2.0. These are 468 general terms, abstract from any particular assertion format. 469 Mappings of these terms into specific representations are provided by 470 profiles of this specification. 472 Issuer The unique identifier for the entity that issued the 473 assertion. Generally this is the entity that holds the key 474 material used to generate the assertion. Examples of issuers are 475 OAuth clients (when assertions are self-issued) and third party 476 security token services. 478 Subject A unique identifier for the subject of the assertion. When 479 using assertions for client authentication, the Subject SHOULD be 480 the "client_id" of the OAuth client. When using assertions as an 481 authorization grant, the Subject MUST identify an authorized 482 accessor for which the access token is being requested (typically 483 the resource owner, or an authorized delegate). 485 Audience A value that identifies the parties intended to process the 486 assertion. An audience value MAY be the URL of the Token Endpoint 487 as defined in Section 3.2 of OAuth 2.0 [RFC6749]. 489 Issued At The time at which the assertion was issued. While the 490 serialization may differ by assertion format, this is always 491 expressed in UTC with no time zone component. 493 Expires At The time at which the assertion expires. While the 494 serialization may differ by assertion format, this is always 495 expressed in UTC with no time zone component. 497 Assertion ID A nonce or unique identifier for the assertion. The 498 Assertion ID may be used by implementations requiring message de- 499 duplication for one-time use assertions. Any entity that assigns 500 an identifier MUST ensure that there is negligible probability 501 that that entity or any other entity will accidentally assign the 502 same identifier to a different data object. 504 5.2. General Assertion Format and Processing Rules 506 The following are general format and processing rules for the use of 507 assertions in OAuth: 509 o The assertion MUST contain an Issuer. The Issuer MUST identify 510 the entity that issued the assertion as recognized by the 511 Authorization Server. If an assertion is self-issued, the Issuer 512 SHOULD be the "client_id". 514 o The assertion SHOULD contain a Subject. The Subject MUST identify 515 an authorized accessor for which the access token is being 516 requested (typically the resource owner, or an authorized 517 delegate). When the client is acting on behalf of itself, the 518 Subject SHOULD be the "client_id". 520 o The assertion MUST contain an Audience that identifies the 521 Authorization Server as the intended audience. The Authorization 522 Server MUST verify that it is an intended audience for the 523 assertion. The Audience SHOULD be the URL of the Authorization 524 Server's Token Endpoint. 526 o The assertion MUST contain an Expires At entity that limits the 527 time window during which the assertion can be used. The 528 authorization server MUST verify that the expiration time has not 529 passed, subject to allowable clock skew between systems. The 530 authorization server SHOULD reject assertions with an Expires At 531 attribute value that is unreasonably far in the future. 533 o The assertion MAY contain an Issued At entity containing the UTC 534 time at which the assertion was issued. 536 o The assertion MAY contain an Assertion ID. An Authorization 537 Server MAY dictate that Assertion ID is mandatory. 539 o The Authorization Server MUST validate the assertion's signature 540 to verify the Issuer of the assertion. The algorithm used to 541 validate the signature, and the mechanism for designating the 542 secret used to generate the assertion, are beyond the scope of 543 this specification. 545 6. Specific Assertion Format and Processing Rules 547 The following clarifies the format and processing rules defined in 548 Section 4 and Section 5 for a number of common use cases: 550 6.1. Client Authentication 552 When a client uses an assertion for authentication, it SHOULD do so 553 according to Section 4.2. The following format and processing rules 554 apply: 556 o The "client_assertion_type" HTTP parameter MUST identify the 557 assertion format being used for authentication. 559 o The "client_assertion" HTTP parameter MUST contain the serialized 560 assertion in a format indicated by the "client_assertion_type" 561 parameter. 563 o The Subject SHOULD be the "client_id". 565 o The Issuer of the assertion MUST identify the entity that issued 566 the assertion as recognized by the Authorization Server. If the 567 assertion is self-issued, the Issuer SHOULD be the "client_id". 569 o The Audience of the assertion MUST identify the Authorization 570 Server and SHOULD be the URL of the Token Endpoint. 572 o The Authorization Server MUST verify the assertion's signature or 573 keyed message digest to determine the validity of the issuer and 574 the content of the assertion. 576 The following non-normative example demonstrates a client 577 authentication using an assertion during an Access Token Request, as 578 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 579 breaks for display purposes only): 581 POST /token HTTP/1.1 582 Host: server.example.com 583 Content-Type: application/x-www-form-urlencoded 585 grant_type=authorization_code& 586 code=i1WsRn1uB1& 587 client_id=s6BhdRkqt3& 588 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 589 %3Aclient-assertion-type%3Asaml2-bearer& 590 client_assertion=PHNhb...[omitted for brevity]...ZT4 592 6.2. Client Acting on Behalf of Itself 594 When a client is accessing resources on behalf of itself, it SHOULD 595 do so in a manner analogous to the Client Credentials flow defined in 596 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 597 combines both the authentication and authorization grant usage 598 patterns. In this case, the interactions with the authorization 599 server SHOULD be treated as using an assertion for Client 600 Authentication according to Section 4.2, with the addition of a 601 grant_type parameter. The following format and processing rules 602 apply: 604 o The grant_type HTTP request parameter MUST be 605 "client_credentials". 607 o The "client_assertion_type" HTTP parameter MUST identify the 608 assertion format. 610 o The "client_assertion" HTTP parameter MUST contain the serialized 611 assertion as in a format indicated by the "client_assertion_type" 612 parameter. 614 o The Issuer of the assertion MUST identify the entity that issued 615 the assertion as recognized by the Authorization Server. If the 616 assertion is self-issued, the Issuer SHOULD be the "client_id". 617 If the assertion was issued by a Security Token Service (STS), the 618 Issuer SHOULD identify the STS as recognized by the Authorization 619 Server. 621 o The Subject SHOULD be the "client_id". 623 o The Audience of the assertion MUST identify the Authorization 624 Server and SHOULD be the URL of the Token Endpoint. 626 o The Authorization Server MUST validate the assertion's signature 627 to verify the Issuer of the assertion. 629 The following non-normative example demonstrates an assertion being 630 used for a Client Credentials Access Token Request, as defined in 631 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 632 display purposes only): 634 POST /token HTTP/1.1 635 Host: server.example.com 636 Content-Type: application/x-www-form-urlencoded 638 client_id=s6BhdRkqt3& 639 grant_type=client_credentials& 640 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 641 %3Aclient-assertion-type%3Asaml2-bearer& 642 client_assertion=PHNhbW...[omitted for brevity]...ZT 644 6.3. Client Acting on Behalf of a User 646 When a client is accessing resources on behalf of a user, it SHOULD 647 be treated as using an assertion as an Authorization Grant according 648 to Section 4.1. The following format and processing rules apply: 650 o The grant_type HTTP request parameter MUST indicate the assertion 651 format. 653 o The assertion HTTP parameter MUST contain the serialized assertion 654 as in a format indicated by the grant_type parameter. 656 o The Issuer of the assertion MUST identify the entity that issued 657 the assertion as recognized by the Authorization Server. If the 658 assertion is self-issued, the Issuer SHOULD be the "client_id". 659 If the assertion was issued by a Security Token Service (STS), the 660 Issuer SHOULD identify the STS as recognized by the Authorization 661 Server. 663 o The Subject MUST identify an authorized accessor for which the 664 access token is being requested (typically the resource owner, or 665 an authorized delegate). 667 o The Audience of the assertion MUST identify the Authorization 668 Server and MAY be the URL of the Token Endpoint. 670 o The Authorization Server MUST validate the assertion's signature 671 to verify the Issuer of the assertion. 673 The following non-normative example demonstrates a client using an 674 assertion as an Authorization Grant during an Access Token Request, 675 as defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 676 breaks for display purposes only): 678 POST /token HTTP/1.1 679 Host: server.example.com 680 Content-Type: application/x-www-form-urlencoded 682 client_id=s6BhdRkqt3& 683 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 684 assertion=PHNhbWxwOl...[omitted for brevity]...ZT 686 6.4. Client Acting on Behalf of an Anonymous User 688 When a client is accessing resources on behalf of an anonymous user, 689 the following format and processing rules apply: 691 o The grant_type HTTP request parameter MUST indicate the assertion 692 format. 694 o The assertion HTTP parameter MUST contain the serialized assertion 695 as in a format indicated by the grant_type parameter. 697 o The Issuer of the assertion MUST identify the entity that issued 698 the assertion as recognized by the Authorization Server. If the 699 assertion is self-issued, the Issuer SHOULD be the "client_id". 700 If the assertion was issued by a Security Token Service (STS), the 701 Issuer SHOULD identify the STS as recognized by the Authorization 702 Server. 704 o The Subject SHOULD indicate to the Authorization Server that the 705 client is acting on-behalf of an anonymous user as defined by the 706 Authorization Server. It is implied that authorization is based 707 upon additional criteria, such as additional attributes or claims 708 provided in the assertion. For example, a client may present an 709 assertion from a trusted issuer asserting that the bearer is over 710 18 via an included claim. In this case, no additional information 711 about the user's identity is included, yet all the data needed to 712 issue an access token is present. 714 o The Audience of the assertion MUST identify the Authorization 715 Server and MAY be the URL of the Token Endpoint. 717 o The Authorization Server MUST validate the assertion's signature 718 to verify the Issuer of the assertion. 720 7. Security Considerations 722 This section discusses security considerations that apply when using 723 assertions with OAuth 2.0 as described in this document. As 724 discussed in Section 3, there are two different ways to obtain 725 assertions: either as self-issued or obtained from a third party 726 token service. While the actual interactions for obtaining an 727 assertion are outside the scope of this document, the details are 728 important from a security perspective. Section 3 discusses the high 729 level architectural aspects. Many of the security considerations 730 discussed in this section are applicable to both the OAuth exchange 731 as well as the client obtaining the assertion. 733 The remainder of this section focuses on the exchanges that concern 734 presenting an assertion for client authentication and for the 735 authorization grant. 737 7.1. Forged Assertion 739 Threat: 740 An adversary could forge or alter an assertion in order to obtain 741 an access token (in case of the authorization grant) or to 742 impersonate a client (in case of the client authentication 743 mechanism). 745 Countermeasures: 746 To avoid this kind of attack, the entities must assure that proper 747 mechanisms for protecting the integrity of the assertion are 748 employed. This includes the issuer digitally signing the 749 assertion or computing a keyed message digest over the assertion. 751 7.2. Stolen Assertion 753 Threat: 754 An adversary may be able obtain an assertion (e.g., by 755 eavesdropping) and then reuse it (replay it) at a later point in 756 time. 758 Countermeasures: 759 The primary mitigation for this threat is the use of a secure 760 communication channel with server authentication for all network 761 exchanges. 763 An assertion may also contain several elements to prevent replay 764 attacks. There is, however, a clear tradeoff between reusing an 765 assertion for multiple exchanges and obtaining and creating new 766 fresh assertions. 768 Authorization Servers and Resource Servers may use a combination 769 of the Assertion ID and Issued At/Expires At attributes for replay 770 protection. Previously processed assertions may be rejected based 771 on the Assertion ID. The addition of the validity window relieves 772 the authorization server from maintaining an infinite state table 773 of processed Assertion IDs. 775 7.3. Unauthorized Disclosure of Personal Information 777 Threat: 778 The ability for other entities to obtain information about an 779 individual, such as authentication information, role in an 780 organization, or other authorization relevant information, raises 781 privacy concerns. 783 Countermeasures: 784 To address the threats, two cases need to be differentiated: 786 First, a third party that did not participate in any of the 787 exchange is prevented from eavesdropping on the content of the 788 assertion by employing confidentiality protection of the exchange 789 using TLS. This ensures that an eavesdropper on the wire is 790 unable to obtain information. However, this does not prevent 791 legitimate protocol entities from obtaining information from an 792 assertion they may not have been allowed to obtain. Some 793 assertion formats allow for the assertion to be encrypted, 794 preventing unauthorized parties from inspecting the content. 796 Second, an Authorization Server may obtain an assertion that was 797 created by a third party token service and that token service may 798 have placed attributes into the assertion. To mitigate potential 799 privacy problems, prior consent from the resource owner has to be 800 obtained. OAuth itself does not directly provide such 801 capabilities, but this consent approval may be obtained using 802 other identity management protocols, user consent interactions, or 803 in an out-of-band fashion. 805 For the cases where a third party token service creates assertions 806 to be used for client authentication, privacy concerns are 807 typically lower, since many of these clients are Web servers 808 rather than individual devices operated by humans. If the 809 assertions are used for client authentication of devices or 810 software that can be closely linked to end users, then privacy 811 protection safeguards need to be taken into consideration. 813 Further guidance on privacy friendly protocol design can be found 814 in [I-D.iab-privacy-considerations]. 816 8. IANA Considerations 818 This is a request to add three values, as listed in the sub-sections 819 below, to the "OAuth Parameters" registry established by RFC 6749. 820 [RFC6749] 822 8.1. assertion Parameter Registration 824 o Parameter name: assertion 826 o Parameter usage location: token request 828 o Change controller: IETF 830 o Specification document(s): [[this document]] 832 8.2. client_assertion Parameter Registration 834 o Parameter name: client_assertion 836 o Parameter usage location: token request 838 o Change controller: IETF 840 o Specification document(s): [[this document]] 842 8.3. client_assertion_type Parameter Registration 844 o Parameter name: client_assertion_type 846 o Parameter usage location: token request 848 o Change controller: IETF 850 o Specification document(s): [[this document]] 852 9. References 854 9.1. Normative References 856 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 857 Requirement Levels", BCP 14, RFC 2119, March 1997. 859 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 860 RFC 6749, October 2012. 862 9.2. Informative References 864 [I-D.iab-privacy-considerations] 865 Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 866 Morris, J., Hansen, M., and R. Smith, "Privacy 867 Considerations for Internet Protocols", 868 draft-iab-privacy-considerations-03 (work in progress), 869 July 2012. 871 [I-D.ietf-oauth-jwt-bearer] 872 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 873 (JWT) Bearer Token Profiles for OAuth 2.0", 874 draft-ietf-oauth-jwt-bearer-04 (work in progress), 875 December 2012. 877 [I-D.ietf-oauth-saml2-bearer] 878 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 879 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-15 880 (work in progress), November 2012. 882 [OASIS.WS-Trust] 883 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 884 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", 885 Feb 2009. 887 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 888 for OAuth", RFC 6755, October 2012. 890 Appendix A. Acknowledgements 892 The authors wish to thank the following people that have influenced 893 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 894 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 895 specification, and the members of the OAuth working group. 897 Appendix B. Document History 899 [[ to be removed by the RFC editor before publication as an RFC ]] 901 draft-ietf-oauth-assertions-10 903 o Changed term "Principal" to "Subject". 905 o Added Interoperability Considerations section. 907 o Applied Shawn Emery's comments from the security directorate 908 review, including correcting urn:ietf:params:oauth:grant_type:* to 909 urn:ietf:params:oauth:grant-type:*. 911 draft-ietf-oauth-assertions-09 913 o Allow audience values to not be URIs. 915 o Added informative references to draft-ietf-oauth-saml2-bearer and 916 draft-ietf-oauth-jwt-bearer. 918 o Clarified that the statements about possible issuers are non- 919 normative by using the language "Examples of issuers". 921 draft-ietf-oauth-assertions-08 923 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 925 o Tidy up IANA consideration section 927 draft-ietf-oauth-assertions-07 929 o Reference RFC 6749. 931 o Remove extraneous word per 932 http://www.ietf.org/mail-archive/web/oauth/current/msg10029.html 934 draft-ietf-oauth-assertions-06 936 o Add more text to intro explaining that an assertion grant type can 937 be used with or without client authentication/identification and 938 that client assertion authentication is nothing more than an 939 alternative way for a client to authenticate to the token endpoint 941 draft-ietf-oauth-assertions-05 943 o Non-normative editorial cleanups 945 draft-ietf-oauth-assertions-04 947 o Updated document to incorporate the review comments from the 948 shepherd - thread and alternative draft at 949 http://www.ietf.org/mail-archive/web/oauth/current/msg09437.html 951 o Added reference to draft-ietf-oauth-urn-sub-ns and include 952 suggestions on 953 urn:ietf:params:oauth:[grant-type|client-assertion-type]:* URNs 955 o updated reference to draft-ietf-oauth-v2 from -25 to -26 957 draft-ietf-oauth-assertions-02 959 o Added text about limited lifetime ATs and RTs per 960 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 962 o Changed the line breaks in some examples to avoid awkward 963 rendering to text format. Also removed encoded '=' padding from a 964 few examples because both known derivative specs, SAML and JWT, 965 omit the padding char in serialization/encoding. 967 o Remove section 7 on error responses and move that (somewhat 968 modified) content into subsections of section 4 broken up by 969 authn/authz per 970 http://www.ietf.org/mail-archive/web/oauth/current/msg08735.html. 972 o Rework the text about "MUST validate ... in order to establish a 973 mapping between ..." per 974 http://www.ietf.org/mail-archive/web/oauth/current/msg08872.html 975 and 976 http://www.ietf.org/mail-archive/web/oauth/current/msg08749.html. 978 o Change "The Principal MUST identify an authorized accessor. If 979 the assertion is self-issued, the Principal SHOULD be the 980 client_id" in 6.1 per 981 http://www.ietf.org/mail-archive/web/oauth/current/msg08873.html. 983 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 984 oauth-v2 (rather than self) 985 http://www.ietf.org/mail-archive/web/oauth/current/msg08874.html. 987 o Move the "Section 3 of" out of the xref to hopefully fix the link 988 in 4.1 and remove the client_id bullet from 4.2 per 989 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 991 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 992 some then redundant text per 993 http://www.ietf.org/mail-archive/web/oauth/current/msg08890.html. 995 o Change "The following format and processing rules SHOULD be 996 applied" to "The following format and processing rules apply" in 997 sections 6.x to remove conflicting normative qualification of 998 other normative statements per 999 http://www.ietf.org/mail-archive/web/oauth/current/msg08892.html. 1001 o Add text the client_id must id the client to 4.1 and remove 1002 similar text from other places per 1003 http://www.ietf.org/mail-archive/web/oauth/current/msg08893.html. 1005 o Remove the MUST from the text prior to the HTTP parameter 1006 definitions per 1007 http://www.ietf.org/mail-archive/web/oauth/current/msg08920.html. 1009 o Updated examples to use grant_type and client_assertion_type 1010 values from the OAuth SAML Assertion Profiles spec. 1012 Authors' Addresses 1014 Brian Campbell 1015 Ping Identity Corp. 1017 Email: brian.d.campbell@gmail.com 1019 Chuck Mortimore 1020 Salesforce.com 1022 Email: cmortimore@salesforce.com 1024 Michael B. Jones 1025 Microsoft 1027 Email: mbj@microsoft.com 1029 Yaron Y. Goland 1030 Microsoft 1032 Email: yarong@microsoft.com