idnits 2.17.1 draft-ietf-oauth-assertions-11.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 (March 29, 2013) is 4039 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 (-30) exists of draft-ietf-oauth-dyn-reg-08 == 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 (~~), 5 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: September 30, 2013 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 March 29, 2013 11 Assertion Framework for OAuth 2.0 Client Authentication and 12 Authorization Grants 13 draft-ietf-oauth-assertions-11 15 Abstract 17 This specification provides a framework for the use of assertions 18 with OAuth 2.0 in the form of a new client authentication mechanism 19 and a new authorization grant type. Mechanisms are specified for 20 transporting assertions during interactions with a token endpoint, as 21 well as general processing rules. 23 The intent of this specification is to provide a common framework for 24 OAuth 2.0 to interwork with other identity systems using assertions, 25 and to provide alternative client authentication mechanisms. 27 Note that this specification only defines abstract message flows and 28 processing rules. In order to be implementable, companion 29 specifications are necessary to provide the corresponding concrete 30 instantiations. 32 Status of this Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on September 30, 2013. 49 Copyright Notice 51 Copyright (c) 2013 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 3. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 8 70 4.1. Using Assertions as Authorization Grants . . . . . . . . . 8 71 4.1.1. Error Responses . . . . . . . . . . . . . . . . . . . 9 72 4.2. Using Assertions for Client Authentication . . . . . . . . 9 73 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 10 74 5. Assertion Content and Processing . . . . . . . . . . . . . . . 11 75 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 11 76 5.2. General Assertion Format and Processing Rules . . . . . . 12 77 6. Common Scenarios . . . . . . . . . . . . . . . . . . . . . . . 13 78 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 13 79 6.2. Client Acting on Behalf of Itself . . . . . . . . . . . . 13 80 6.3. Client Acting on Behalf of a User . . . . . . . . . . . . 14 81 6.3.1. Client Acting on Behalf of an Anonymous User . . . . . 14 82 7. Interoperability Considerations . . . . . . . . . . . . . . . 14 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 84 8.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . . 15 85 8.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . . 16 86 8.3. Unauthorized Disclosure of Personal Information . . . . . 16 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 88 9.1. assertion Parameter Registration . . . . . . . . . . . . . 17 89 9.2. client_assertion Parameter Registration . . . . . . . . . 17 90 9.3. client_assertion_type Parameter Registration . . . . . . . 18 91 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 92 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 93 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 94 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 95 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 98 1. Introduction 100 An assertion is a package of information that facilitates the sharing 101 of identity and security information across security domains. 102 Section 3 provides a more detailed description of the concept of an 103 assertion for the purpose of this specification. 105 OAuth 2.0 [RFC6749] is an authorization framework that enables a 106 third-party application to obtain limited access to a protected HTTP 107 resource. In OAuth, those third-party applications are called 108 clients; they access protected resources by presenting an access 109 token to the HTTP resource. Access tokens are issued to clients by 110 an authorization server with the (sometimes implicit) approval of the 111 resource owner. These access tokens are typically obtained by 112 exchanging an authorization grant, which represents the authorization 113 granted by the resource owner (or by a privileged administrator). 114 Several authorization grant types are defined to support a wide range 115 of client types and user experiences. OAuth also provides an 116 extensibility mechanism for defining additional grant types, which 117 can serve as a bridge between OAuth and other protocol frameworks. 119 This specification provides a general framework for the use of 120 assertions as authorization grants with OAuth 2.0. It also provides 121 a framework for assertions to be used for client authentication. It 122 provides generic mechanisms for transporting assertions during 123 interactions with an authorization server's token endpoint, as well 124 as general rules for the content and processing of those assertions. 125 The intent is to provide an alternative client authentication 126 mechanism (one that doesn't send client secrets), as well as to 127 facilitate the use of OAuth 2.0 in client-server integration 128 scenarios, where the end-user may not be present. 130 This specification only defines abstract message flows and processing 131 rules. In order to be implementable, companion specifications are 132 necessary to provide the corresponding concrete instantiations. For 133 instance, SAML 2.0 Profile for OAuth 2.0 Client Authentication and 134 Authorization Grants [I-D.ietf-oauth-saml2-bearer] defines a concrete 135 instantiation for SAML 2.0 assertions and JSON Web Token (JWT) 136 Profile for OAuth 2.0 Client Authentication and Authorization Grants 137 [I-D.ietf-oauth-jwt-bearer] defines a concrete instantiation for 138 JWTs. 140 Note: The use of assertions for client authentication is orthogonal 141 to and separable from using assertions as an authorization grant. 142 They can be used either in combination or separately. Client 143 assertion authentication is nothing more than an alternative way for 144 a client to authenticate to the token endpoint and must be used in 145 conjunction with some grant type to form a complete and meaningful 146 protocol request. Assertion authorization grants may be used with or 147 without client authentication or identification. Whether or not 148 client authentication is needed in conjunction with an assertion 149 authorization grant, as well as the supported types of client 150 authentication, are policy decisions at the discretion of the 151 authorization server. 153 2. Terminology 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 157 document are to be interpreted as described in [RFC2119] . 159 Throughout this document, values are quoted to indicate that they are 160 to be taken literally. When using these values in protocol messages, 161 the quotes must not be used as part of the value. 163 3. Framework 165 An assertion is a package of information that allows identity and 166 security information to be shared across security domains. An 167 assertion typically contains information about a subject or 168 principal, information about the party that issued the assertion and 169 when was it issued, as well as the conditions under which the 170 assertion is to be considered valid, such as when and where it can be 171 used. 173 The entity that creates and signs or integrity protects the assertion 174 is typically known as the "Issuer" and the entity that consumes the 175 assertion and relies on its information is typically known as the 176 "Relying Party". In the context of this document, the authorization 177 server acts as a relying party. 179 Assertions used in the protocol exchanges defined by this 180 specification MUST always be protected against tampering using a 181 digital signature or a keyed message digest applied by the issuer. 182 An assertion MAY additionally be encrypted, preventing unauthorized 183 parties from inspecting the content. 185 Although this document does not define the processes by which the 186 client obtains the assertion (prior to sending it to the 187 authorization server), there are two common patterns described below. 189 In the first pattern, depicted in Figure 1, the client obtains an 190 assertion from a third party entity capable of issuing, renewing, 191 transforming, and validating security tokens. Typically such an 192 entity is known as a "Security Token Service" (STS) or just "Token 193 Service" and a trust relationship (usually manifested in the exchange 194 of some kind of key material) exists between the token service and 195 the relying party. The token service is the assertion issuer; its 196 role is to fulfill requests from clients, which present various 197 credentials, and mint assertions as requested, fill them with 198 appropriate information, and integrity protect them with a signature 199 or message authentication code. WS-Trust [OASIS.WS-Trust] is one 200 available standard for requesting security tokens (assertions). 202 Relying 203 Party Client Token Service 204 | | | 205 | | 1) Request Assertion | 206 | |------------------------>| 207 | | | 208 | | 2) Assertion | 209 | |<------------------------| 210 | 3) Assertion | | 211 |<-------------------------| | 212 | | | 213 | 4) OK or Failure | | 214 |------------------------->| | 215 | | | 216 | | | 218 Figure 1: Third Party Created Assertion 220 In the second pattern, depicted in Figure 2, the client creates 221 assertions locally. To apply the signatures or message 222 authentication codes to assertions, it has to obtain key material: 223 either symmetric keys or asymmetric key pairs. The mechanisms for 224 obtaining this key material are beyond the scope of this 225 specification. 227 Although assertions are usually used to convey identity and security 228 information, self-issued assertions can also serve a different 229 purpose. They can be used to demonstrate knowledge of some secret, 230 such as a client secret, without actually communicating the secret 231 directly in the transaction. In that case, additional information 232 included in the assertion by the client itself will be of limited 233 value to the relying party and, for this reason, only a bare minimum 234 of information is typically included in such an assertion, such as 235 information about issuing and usage conditions. 237 Relying 238 Party Client 239 | | 240 | | 1) Create 241 | | Assertion 242 | |--------------+ 243 | | | 244 | | 2) Assertion | 245 | |<-------------+ 246 | 3) Assertion | 247 |<-------------------------| 248 | | 249 | 4) OK or Failure | 250 |------------------------->| 251 | | 252 | | 254 Figure 2: Self-Issued Assertion 256 Deployments need to determine the appropriate variant to use based on 257 the required level of security, the trust relationship between the 258 entities, and other factors. 260 From the perspective of what must be done by the entity presenting 261 the assertion, there are two general types of assertions: 263 1. Bearer Assertions: Any entity in possession of a bearer assertion 264 (the bearer) can use it to get access to the associated resources 265 (without demonstrating possession of a cryptographic key). To 266 prevent misuse, bearer assertions need to be protected from 267 disclosure in storage and in transport. Secure communication 268 channels are required between all entities to avoid leaking the 269 assertion to unauthorized parties. 271 2. Holder-of-Key Assertions: To access the associated resources, the 272 entity presenting the assertion must demonstrate possession of 273 additional cryptographic material. The token service thereby 274 binds a key identifier to the assertion and the client has to 275 demonstrate to the relying party that it knows the key 276 corresponding to that identifier when presenting the assertion. 277 This mechanism provides additional security properties. 279 The protocol parameters and processing rules defined in this document 280 are intended to support a client presenting a bearer assertion to an 281 authorization server. The use of holder-of-key assertions are not 282 precluded by this document, but additional protocol details would 283 need to be specified. 285 4. Transporting Assertions 287 This section defines HTTP parameters for transporting assertions 288 during interactions with a token endpoint of an OAuth authorization 289 server. Because requests to the token endpoint result in the 290 transmission of clear-text credentials (in both the HTTP request and 291 response), all requests to the token endpoint MUST use TLS, as 292 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 294 4.1. Using Assertions as Authorization Grants 296 This section defines the use of assertions as authorization grants, 297 based on the definition provided in Section 4.5 of OAuth 2.0 298 [RFC6749]. When using assertions as authorization grants, the client 299 includes the assertion and related information using the following 300 HTTP request parameters: 302 grant_type REQUIRED. The format of the assertion as defined by the 303 authorization server. The value MUST be an absolute URI. 305 assertion REQUIRED. The assertion being used as an authorization 306 grant. Specific serialization of the assertion is defined by 307 profile documents. The serialization MUST be encoded for 308 transport within HTTP forms. It is RECOMMENDED that base64url be 309 used. 311 scope OPTIONAL. The requested scope as described in Section 3.3 of 312 OAuth 2.0 [RFC6749]. When exchanging assertions for access 313 tokens, the authorization for the token has been previously 314 granted through some out-of-band mechanism. As such, the 315 requested scope MUST be equal or lesser than the scope originally 316 granted to the authorized accessor. If the scope parameter and/or 317 value are omitted, the scope MUST be treated as equal to the scope 318 originally granted to the authorized accessor. The Authorization 319 Server MUST limit the scope of the issued access token to be equal 320 or lesser than the scope originally granted to the authorized 321 accessor. 323 Authentication of the client is optional, as described in Section 324 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the "client_id" is 325 only needed when a form of client authentication that relies on the 326 parameter is used. 328 The following non-normative example demonstrates an assertion being 329 used as an authorization grant (with extra line breaks for display 330 purposes only): 332 POST /token HTTP/1.1 333 Host: server.example.com 334 Content-Type: application/x-www-form-urlencoded 336 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 337 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 339 An assertion used in this context is generally a short lived 340 representation of the authorization grant and authorization servers 341 SHOULD NOT issue access tokens with a lifetime that exceeds the 342 validity period of the assertion by a significant period. In 343 practice, that will usually mean that refresh tokens are not issued 344 in response to assertion grant requests and access tokens will be 345 issued with a reasonably short lifetime. Clients can refresh an 346 expired access token by requesting a new one using the same 347 assertion, if it is still valid, or with a new assertion. 349 An IETF URN for use as the "grant_type" value can be requested using 350 the template in [RFC6755]. A URN of the form 351 urn:ietf:params:oauth:grant-type:* is suggested. 353 4.1.1. Error Responses 355 If an assertion is not valid or has expired, the Authorization Server 356 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 357 The value of the "error" parameter MUST be the "invalid_grant" error 358 code. The authorization server MAY include additional information 359 regarding the reasons the assertion was considered invalid using the 360 "error_description" or "error_uri" parameters. 362 For example: 364 HTTP/1.1 400 Bad Request 365 Content-Type: application/json 366 Cache-Control: no-store 368 { 369 "error":"invalid_grant", 370 "error_description":"Audience validation failed" 371 } 373 4.2. Using Assertions for Client Authentication 375 The following section defines the use of assertions as client 376 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 377 When using assertions as client credentials, the client includes the 378 assertion and related information using the following HTTP request 379 parameters: 381 client_assertion_type REQUIRED. The format of the assertion as 382 defined by the authorization server. The value MUST be an 383 absolute URI. 385 client_assertion REQUIRED. The assertion being used to authenticate 386 the client. Specific serialization of the assertion is defined by 387 profile documents. The serialization MUST be encoded for 388 transport within HTTP forms. It is RECOMMENDED that base64url be 389 used. 391 client_id OPTIONAL. The client identifier as described in Section 392 2.2 of OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for 393 client assertion authentication because the client is identified 394 by the subject of the assertion. If present, the value of the 395 "client_id" parameter MUST identify the same client as is 396 identified by the client assertion. 398 The following non-normative example demonstrates a client 399 authenticating using an assertion during an Access Token Request, as 400 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 401 breaks for display purposes only): 403 POST /token HTTP/1.1 404 Host: server.example.com 405 Content-Type: application/x-www-form-urlencoded 407 grant_type=authorization_code& 408 code=i1WsRn1uB1& 409 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 410 %3Aclient-assertion-type%3Asaml2-bearer& 411 client_assertion=PHNhbW...[omitted for brevity]...ZT 413 Token endpoints can differentiate between assertion based credentials 414 and other client credential types by looking for the presence of the 415 "client_assertion" and "client_assertion_type" parameters, which will 416 only be present when using assertions for client authentication. 418 An IETF URN for use as the "client_assertion_type" value may be 419 requested using the template in [RFC6755]. A URN of the form 420 urn:ietf:params:oauth:client-assertion-type:* is suggested. 422 4.2.1. Error Responses 424 If an assertion is invalid for any reason or if more than one client 425 authentication mechanism is used, the Authorization Server MUST 426 construct an error response as defined in OAuth 2.0 [RFC6749]. The 427 value of the "error" parameter MUST be the "invalid_client" error 428 code. The authorization server MAY include additional information 429 regarding the reasons the client assertion was considered invalid 430 using the "error_description" or "error_uri" parameters. 432 For example: 434 HTTP/1.1 400 Bad Request 435 Content-Type: application/json 436 Cache-Control: no-store 438 { 439 "error":"invalid_client" 440 "error_description":"assertion has expired" 441 } 443 5. Assertion Content and Processing 445 This section provides a general content and processing model for the 446 use of assertions in OAuth 2.0 [RFC6749]. 448 5.1. Assertion Metamodel 450 The following are entities and metadata involved in the issuance, 451 exchange, and processing of assertions in OAuth 2.0. These are 452 general terms, abstract from any particular assertion format. 453 Mappings of these terms into specific representations are provided by 454 profiles of this specification. 456 Issuer A unique identifier for the entity that issued the assertion. 457 Generally this is the entity that holds the key material used to 458 sign or integrity protect the assertion. Examples of issuers are 459 OAuth clients (when assertions are self-issued) and third party 460 security token services. If the assertion is self-issued, the 461 Issuer value is the client identifier. If the assertion was 462 issued by a Security Token Service (STS), the Issuer should 463 identify the STS in a manner recognized by the Authorization 464 Server. 466 Subject A unique identifier for the subject of the assertion. 468 * When using assertions for client authentication, the Subject 469 MUST identify the client to the authorization server, typically 470 by using the value of the "client_id" of the OAuth client. 472 * When using assertions as an authorization grant, the Subject 473 MUST identify an authorized accessor for which the access token 474 is being requested (typically the resource owner, or an 475 authorized delegate). 477 Audience A value that identifies the party or parties intended to 478 process the assertion. The URL of the Token Endpoint, as defined 479 in Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate 480 that the authorization server as a valid intended audience of the 481 assertion. 483 Issued At The time at which the assertion was issued. While the 484 serialization may differ by assertion format, it is REQUIRED that 485 the time be expressed in UTC with no time zone component. 487 Expires At The time at which the assertion expires. While the 488 serialization may differ by assertion format, it is REQUIRED that 489 the time be expressed in UTC with no time zone component. 491 Assertion ID A nonce or unique identifier for the assertion. The 492 Assertion ID may be used by implementations requiring message de- 493 duplication for one-time use assertions. Any entity that assigns 494 an identifier MUST ensure that there is negligible probability 495 that that entity or any other entity will accidentally assign the 496 same identifier to a different data object. 498 5.2. General Assertion Format and Processing Rules 500 The following are general format and processing rules for the use of 501 assertions in OAuth: 503 o The assertion MUST contain an Issuer. The Issuer MUST identify 504 the entity that issued the assertion as recognized by the 505 Authorization Server. If an assertion is self-issued, the Issuer 506 MUST be the value of the client's "client_id". 508 o The assertion SHOULD contain a Subject. The Subject MUST identify 509 an authorized accessor for which the access token is being 510 requested (typically the resource owner, or an authorized 511 delegate). When the client is acting on behalf of itself, the 512 Subject SHOULD be the value of the client's "client_id". 514 o The assertion MUST contain an Audience that identifies the 515 Authorization Server as the intended audience. Assertions that do 516 not identify the Authorization Server as an intended audience MUST 517 be rejected. 519 o The assertion MUST contain an Expires At entity that limits the 520 time window during which the assertion can be used. The 521 authorization server MUST reject assertions that have expired 522 (subject to allowable clock skew between systems). The 523 authorization server MAY reject assertions with an Expires At 524 attribute value that is unreasonably far in the future. 526 o The assertion MAY contain an Issued At entity containing the UTC 527 time at which the assertion was issued. 529 o The Authorization Server MUST reject assertions with an invalid 530 signature or keyed message digest. The algorithm used to validate 531 the signature or message authentication code and the mechanism for 532 designating the secret used to generate the signature or message 533 authentication code over the assertion are beyond the scope of 534 this specification. 536 6. Common Scenarios 538 The following provides additional guidance, beyond the format and 539 processing rules defined in Section 4 and Section 5, on assertion use 540 for a number of common use cases. 542 6.1. Client Authentication 544 A client uses an assertion to authenticate to the authorization 545 server's token endpoint by using the "client_assertion_type" and 546 "client_assertion" parameters as defined in Section 4.2. The Subject 547 of the assertion identifies the client. If the assertion is self- 548 issued by the client, the Issuer of the assertion also identifies the 549 client. 551 The example in Section 4.2 that shows a client authenticating using 552 an assertion during an Access Token Request. 554 6.2. Client Acting on Behalf of Itself 556 When a client is accessing resources on behalf of itself, it does so 557 in a manner analogous to the Client Credentials flow defined in 558 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 559 combines both the authentication and authorization grant usage 560 patterns. In this case, the interactions with the authorization 561 server should be treated as using an assertion for Client 562 Authentication according to Section 4.2, while using the grant_type 563 parameter with the value "client_credentials" to indicate that the 564 client is requesting an access token using only its client 565 credentials. 567 The following non-normative example demonstrates an assertion being 568 used for a Client Credentials Access Token Request, as defined in 569 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 570 display purposes only): 572 POST /token HTTP/1.1 573 Host: server.example.com 574 Content-Type: application/x-www-form-urlencoded 576 grant_type=client_credentials& 577 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 578 %3Aclient-assertion-type%3Asaml2-bearer& 579 client_assertion=PHNhbW...[omitted for brevity]...ZT 581 6.3. Client Acting on Behalf of a User 583 When a client is accessing resources on behalf of a user, it does so 584 by using the "grant_type" and "assertion" parameters as defined in 585 Section 4.1. The Subject identifies an authorized accessor for which 586 the access token is being requested (typically the resource owner, or 587 an authorized delegate). 589 The example in Section 4.1 that shows a client making an Access Token 590 Request using an assertion as an Authorization Grant. 592 6.3.1. Client Acting on Behalf of an Anonymous User 594 When a client is accessing resources on behalf of an anonymous user, 595 the Subject indicates to the Authorization Server that the client is 596 acting on-behalf of an anonymous user as defined by the Authorization 597 Server. It is implied that authorization is based upon additional 598 criteria, such as additional attributes or claims provided in the 599 assertion. For example, a client may present an assertion from a 600 trusted issuer asserting that the bearer is over 18 via an included 601 claim. In this case, no additional information about the user's 602 identity is included, yet all the data needed to issue an access 603 token is present. 605 7. Interoperability Considerations 607 This specification defines a framework for using assertions with 608 OAuth 2.0. However, as an abstract framework in which the data 609 formats used for representing many values are not defined, on its 610 own, this specification is not sufficient to produce interoperable 611 implementations. 613 Two other specifications that profile this framework for specific 614 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 615 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 616 uses JSON Web Tokens (JWTs). These two instantiations of this 617 framework specify additional details about the assertion encoding and 618 processing rules for using those kinds of assertions with OAuth 2.0. 620 However, even when profiled for specific assertion types, agreements 621 between system entities regarding identifiers, keys, and endpoints 622 are required in order to achieve interoperable deployments. Specific 623 items that require agreement are as follows: values for the issuer 624 and audience identifiers, supported assertion and client 625 authentication types, the location of the token endpoint, and the key 626 used to apply and verify the digital signature or keyed message 627 digest over the assertion. The exchange of such information is 628 explicitly out of scope for this specification. Deployments for 629 particular trust frameworks, circles of trust, or other uses cases 630 will need to agree among the participants on the kinds of values to 631 be used for some abstract fields defined by this specification. In 632 some cases, additional profiles may be created that constrain or 633 prescribe these values or specify how they are to be exchanged. The 634 OAuth 2.0 Dynamic Client Registration Protocol 635 [I-D.ietf-oauth-dyn-reg] is one such profile that enables OAuth 636 Clients to register metadata about themselves at an Authorization 637 Server. 639 8. Security Considerations 641 This section discusses security considerations that apply when using 642 assertions with OAuth 2.0 as described in this document. As 643 discussed in Section 3, there are two different ways to obtain 644 assertions: either as self-issued or obtained from a third party 645 token service. While the actual interactions for obtaining an 646 assertion are outside the scope of this document, the details are 647 important from a security perspective. Section 3 discusses the high 648 level architectural aspects. Many of the security considerations 649 discussed in this section are applicable to both the OAuth exchange 650 as well as the client obtaining the assertion. 652 The remainder of this section focuses on the exchanges that concern 653 presenting an assertion for client authentication and for the 654 authorization grant. 656 8.1. Forged Assertion 658 Threat: 659 An adversary could forge or alter an assertion in order to obtain 660 an access token (in case of the authorization grant) or to 661 impersonate a client (in case of the client authentication 662 mechanism). 664 Countermeasures: 665 To avoid this kind of attack, the entities must assure that proper 666 mechanisms for protecting the integrity of the assertion are 667 employed. This includes the issuer digitally signing the 668 assertion or computing a keyed message digest over the assertion. 670 8.2. Stolen Assertion 672 Threat: 673 An adversary may be able obtain an assertion (e.g., by 674 eavesdropping) and then reuse it (replay it) at a later point in 675 time. 677 Countermeasures: 678 The primary mitigation for this threat is the use of secure 679 communication channels with server authentication for all network 680 exchanges. 682 An assertion may also contain several elements to prevent replay 683 attacks. There is, however, a clear tradeoff between reusing an 684 assertion for multiple exchanges and obtaining and creating new 685 fresh assertions. 687 Authorization Servers and Resource Servers may use a combination 688 of the Assertion ID and Issued At/Expires At attributes for replay 689 protection. Previously processed assertions may be rejected based 690 on the Assertion ID. The addition of the validity window relieves 691 the authorization server from maintaining an infinite state table 692 of processed Assertion IDs. 694 8.3. Unauthorized Disclosure of Personal Information 696 Threat: 697 The ability for other entities to obtain information about an 698 individual, such as authentication information, role in an 699 organization, or other authorization relevant information, raises 700 privacy concerns. 702 Countermeasures: 703 To address the threats, two cases need to be differentiated: 705 First, a third party that did not participate in any of the 706 exchange is prevented from eavesdropping on the content of the 707 assertion by employing confidentiality protection of the exchange 708 using TLS. This ensures that an eavesdropper on the wire is 709 unable to obtain information. However, this does not prevent 710 legitimate protocol entities from obtaining information that they 711 are not allowed to possess from assertions. Some assertion 712 formats allow for the assertion to be encrypted, preventing 713 unauthorized parties from inspecting the content. 715 Second, an Authorization Server may obtain an assertion that was 716 created by a third party token service and that token service may 717 have placed attributes into the assertion. To mitigate potential 718 privacy problems, prior consent for the release of such attribute 719 information from the resource owner should be obtained. OAuth 720 itself does not directly provide such capabilities, but this 721 consent approval may be obtained using other identity management 722 protocols, user consent interactions, or in an out-of-band 723 fashion. 725 For the cases where a third party token service creates assertions 726 to be used for client authentication, privacy concerns are 727 typically lower, since many of these clients are Web servers 728 rather than individual devices operated by humans. If the 729 assertions are used for client authentication of devices or 730 software that can be closely linked to end users, then privacy 731 protection safeguards need to be taken into consideration. 733 Further guidance on privacy friendly protocol design can be found 734 in [I-D.iab-privacy-considerations]. 736 9. IANA Considerations 738 This is a request to add three values, as listed in the sub-sections 739 below, to the "OAuth Parameters" registry established by RFC 6749 740 [RFC6749]. 742 9.1. assertion Parameter Registration 744 o Parameter name: assertion 746 o Parameter usage location: token request 748 o Change controller: IETF 750 o Specification document(s): [[this document]] 752 9.2. client_assertion Parameter Registration 754 o Parameter name: client_assertion 755 o Parameter usage location: token request 757 o Change controller: IETF 759 o Specification document(s): [[this document]] 761 9.3. client_assertion_type Parameter Registration 763 o Parameter name: client_assertion_type 765 o Parameter usage location: token request 767 o Change controller: IETF 769 o Specification document(s): [[this document]] 771 10. References 773 10.1. Normative References 775 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 776 Requirement Levels", BCP 14, RFC 2119, March 1997. 778 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 779 RFC 6749, October 2012. 781 10.2. Informative References 783 [I-D.iab-privacy-considerations] 784 Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 785 Morris, J., Hansen, M., and R. Smith, "Privacy 786 Considerations for Internet Protocols", 787 draft-iab-privacy-considerations-03 (work in progress), 788 July 2012. 790 [I-D.ietf-oauth-dyn-reg] 791 Richer, J., Bradley, J., Jones, M., and M. Machulak, 792 "OAuth 2.0 Dynamic Client Registration Protocol", 793 draft-ietf-oauth-dyn-reg-08 (work in progress), 794 March 2013. 796 [I-D.ietf-oauth-jwt-bearer] 797 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 798 (JWT) Bearer Token Profiles for OAuth 2.0", 799 draft-ietf-oauth-jwt-bearer-04 (work in progress), 800 December 2012. 802 [I-D.ietf-oauth-saml2-bearer] 803 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 804 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-15 805 (work in progress), November 2012. 807 [OASIS.WS-Trust] 808 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 809 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", 810 Feb 2009. 812 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 813 for OAuth", RFC 6755, October 2012. 815 Appendix A. Acknowledgements 817 The authors wish to thank the following people that have influenced 818 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 819 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 820 specification, and the members of the OAuth working group. 822 Appendix B. Document History 824 [[ to be removed by the RFC editor before publication as an RFC ]] 826 draft-ietf-oauth-assertions-11 828 o Addressed comments from IESG evaluation https:// 829 datatracker.ietf.org/doc/draft-ietf-oauth-assertions/ballot/. 831 o Reworded Interoperability Considerations to state what 832 identifiers, keys, endpoints, etc. need to be exchanged/agreed 833 upon. 835 o Added brief description of assertion to the into and included a 836 reference to Section 3 (Framework) where it's described more. 838 o Changed such that a self-issued assertion must (was should) have 839 the client id as the issuer. 841 o Changed "Specific Assertion Format and Processing Rules" to 842 "Common Scenarios" and reworded to be more suggestive of common 843 practices, rather than trying to be normative. Also removed lots 844 of repetitive text in that section. 846 o Refined language around audience, subject, client identifiers, 847 etc. to hopefully be clearer and less redundant. 849 o Changed title from "Assertion Framework for OAuth 2.0" to 850 "Assertion Framework for OAuth 2.0 Client Authentication and 851 Authorization Grants" to be more explicit about the scope of the 852 document per 853 http://www.ietf.org/mail-archive/web/oauth/current/msg11063.html. 855 o Noted that authentication of the client per Section 3.2.1 of OAuth 856 is optional for an access token request with an assertion as an 857 authorization grant and removed client_id from the associated 858 example. 860 draft-ietf-oauth-assertions-10 862 o Changed term "Principal" to "Subject". 864 o Added Interoperability Considerations section. 866 o Applied Shawn Emery's comments from the security directorate 867 review, including correcting urn:ietf:params:oauth:grant_type:* to 868 urn:ietf:params:oauth:grant-type:*. 870 draft-ietf-oauth-assertions-09 872 o Allow audience values to not be URIs. 874 o Added informative references to draft-ietf-oauth-saml2-bearer and 875 draft-ietf-oauth-jwt-bearer. 877 o Clarified that the statements about possible issuers are non- 878 normative by using the language "Examples of issuers". 880 draft-ietf-oauth-assertions-08 882 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 884 o Tidy up IANA consideration section 886 draft-ietf-oauth-assertions-07 888 o Reference RFC 6749. 890 o Remove extraneous word per 891 http://www.ietf.org/mail-archive/web/oauth/current/msg10029.html 893 draft-ietf-oauth-assertions-06 895 o Add more text to intro explaining that an assertion grant type can 896 be used with or without client authentication/identification and 897 that client assertion authentication is nothing more than an 898 alternative way for a client to authenticate to the token endpoint 900 draft-ietf-oauth-assertions-05 902 o Non-normative editorial cleanups 904 draft-ietf-oauth-assertions-04 906 o Updated document to incorporate the review comments from the 907 shepherd - thread and alternative draft at 908 http://www.ietf.org/mail-archive/web/oauth/current/msg09437.html 910 o Added reference to draft-ietf-oauth-urn-sub-ns and include 911 suggestions on 912 urn:ietf:params:oauth:[grant-type|client-assertion-type]:* URNs 914 draft-ietf-oauth-assertions-03 916 o updated reference to draft-ietf-oauth-v2 from -25 to -26 918 draft-ietf-oauth-assertions-02 920 o Added text about limited lifetime ATs and RTs per 921 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 923 o Changed the line breaks in some examples to avoid awkward 924 rendering to text format. Also removed encoded '=' padding from a 925 few examples because both known derivative specs, SAML and JWT, 926 omit the padding char in serialization/encoding. 928 o Remove section 7 on error responses and move that (somewhat 929 modified) content into subsections of section 4 broken up by 930 authn/authz per 931 http://www.ietf.org/mail-archive/web/oauth/current/msg08735.html. 933 o Rework the text about "MUST validate ... in order to establish a 934 mapping between ..." per 935 http://www.ietf.org/mail-archive/web/oauth/current/msg08872.html 936 and 937 http://www.ietf.org/mail-archive/web/oauth/current/msg08749.html. 939 o Change "The Principal MUST identify an authorized accessor. If 940 the assertion is self-issued, the Principal SHOULD be the 941 client_id" in 6.1 per 942 http://www.ietf.org/mail-archive/web/oauth/current/msg08873.html. 944 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 945 oauth-v2 (rather than self) 946 http://www.ietf.org/mail-archive/web/oauth/current/msg08874.html. 948 o Move the "Section 3 of" out of the xref to hopefully fix the link 949 in 4.1 and remove the client_id bullet from 4.2 per 950 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 952 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 953 some then redundant text per 954 http://www.ietf.org/mail-archive/web/oauth/current/msg08890.html. 956 o Change "The following format and processing rules SHOULD be 957 applied" to "The following format and processing rules apply" in 958 sections 6.x to remove conflicting normative qualification of 959 other normative statements per 960 http://www.ietf.org/mail-archive/web/oauth/current/msg08892.html. 962 o Add text the client_id must id the client to 4.1 and remove 963 similar text from other places per 964 http://www.ietf.org/mail-archive/web/oauth/current/msg08893.html. 966 o Remove the MUST from the text prior to the HTTP parameter 967 definitions per 968 http://www.ietf.org/mail-archive/web/oauth/current/msg08920.html. 970 o Updated examples to use grant_type and client_assertion_type 971 values from the OAuth SAML Assertion Profiles spec. 973 Authors' Addresses 975 Brian Campbell 976 Ping Identity Corp. 978 Email: brian.d.campbell@gmail.com 980 Chuck Mortimore 981 Salesforce.com 983 Email: cmortimore@salesforce.com 984 Michael B. Jones 985 Microsoft 987 Email: mbj@microsoft.com 989 Yaron Y. Goland 990 Microsoft 992 Email: yarong@microsoft.com