idnits 2.17.1 draft-ietf-oauth-assertions-09.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 27, 2012) is 4138 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-03 == 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: June 30, 2013 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 December 27, 2012 11 Assertion Framework for OAuth 2.0 12 draft-ietf-oauth-assertions-09 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 June 30, 2013. 48 Copyright Notice 49 Copyright (c) 2012 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 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 7 68 4.1. Using Assertions as Authorization Grants . . . . . . . . . 7 69 4.1.1. Error Responses . . . . . . . . . . . . . . . . . . . 8 70 4.2. Using Assertions for Client Authentication . . . . . . . . 8 71 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 9 72 5. Assertion Content and Processing . . . . . . . . . . . . . . . 10 73 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 10 74 5.2. General Assertion Format and Processing Rules . . . . . . 11 75 6. Specific Assertion Format and Processing Rules . . . . . . . . 12 76 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 12 77 6.2. Client Acting on Behalf of Itself . . . . . . . . . . . . 13 78 6.3. Client Acting on Behalf of a User . . . . . . . . . . . . 14 79 6.4. Client Acting on Behalf of an Anonymous User . . . . . . . 15 80 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 81 7.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . . 16 82 7.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . . 16 83 7.3. Unauthorized Disclosure of Personal Information . . . . . 17 84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 85 8.1. assertion Parameter Registration . . . . . . . . . . . . . 18 86 8.2. client_assertion Parameter Registration . . . . . . . . . 18 87 8.3. client_assertion_type Parameter Registration . . . . . . . 18 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 18 90 9.2. Informative References . . . . . . . . . . . . . . . . . . 19 91 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 92 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 95 1. Introduction 97 OAuth 2.0 [RFC6749] is an authorization framework that enables a 98 third-party application to obtain limited access to a protected HTTP 99 resource. In OAuth, those third-party applications are called 100 clients; they access protected resources by presenting an access 101 token to the HTTP resource. Access tokens are issued to clients by 102 an authorization server with the (sometimes implicit) approval of the 103 resource owner. These access tokens are typically obtained by 104 exchanging an authorization grant, which represents the authorization 105 granted by the resource owner (or by a privileged administrator). 106 Several authorization grant types are defined to support a wide range 107 of client types and user experiences. OAuth also provides an 108 extensibility mechanism for defining additional grant types, which 109 can serve as a bridge between OAuth and other protocol frameworks. 111 This specification provides a general framework for the use of 112 assertions as authorization grants with OAuth 2.0. It also provides 113 a framework for assertions to be used for client authentication. It 114 provides generic mechanisms for transporting assertions during 115 interactions with an authorization server's token endpoint, as well 116 as general rules for the content and processing of those assertions. 117 The intent is to provide an alternative client authentication 118 mechanism (one that doesn't send client secrets), as well as to 119 facilitate the use of OAuth 2.0 in client-server integration 120 scenarios, where the end-user may not be present. 122 This specification only defines abstract message flows and processing 123 rules. In order to be implementable, companion specifications are 124 necessary to provide the corresponding concrete instantiations. For 125 instance, SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 126 [I-D.ietf-oauth-saml2-bearer] defines a concrete instantiation for 127 SAML 2.0 tokens and JSON Web Token (JWT) Bearer Token Profiles for 128 OAuth 2.0 [I-D.ietf-oauth-jwt-bearer] defines a concrete 129 instantiation for JWT tokens. 131 Note: The use of assertions for client authentication is orthogonal 132 to and separable from using assertions as an authorization grant. 133 They can be used either in combination or separately. Client 134 assertion authentication is nothing more than an alternative way for 135 a client to authenticate to the token endpoint and must be used in 136 conjunction with some grant type to form a complete and meaningful 137 protocol request. Assertion authorization grants may be used with or 138 without client authentication or identification. Whether or not 139 client authentication is needed in conjunction with an assertion 140 authorization grant, as well as the supported types of client 141 authentication, are policy decisions at the discretion of the 142 authorization server. 144 2. Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 148 document are to be interpreted as described in [RFC2119] . 150 Throughout this document, values are quoted to indicate that they are 151 to be taken literally. When using these values in protocol messages, 152 the quotes must not be used as part of the value. 154 3. Framework 156 An assertion is a package of information that allows identity and 157 security information to be shared across security domains. An 158 assertion typically contains information about a subject or 159 principal, information about the party that issued the assertion and 160 when was it issued, as well as the conditions under which the 161 assertion is to be considered valid, such as when and where it can be 162 used. 164 The entity that creates and signs the assertion is typically known as 165 the "Issuer" and the entity that consumes the assertion and relies on 166 its information is typically known as the "Relying Party". In the 167 context of this document, the authorization server acts as a relying 168 party. 170 Assertions used in the protocol exchanges defined by this 171 specification MUST always be protected against tampering using a 172 digital signature or a keyed message digest applied by the issuer. 173 An assertion MAY additionally be encrypted, preventing unauthorized 174 parties from inspecting the content. 176 Although this document does not define the processes by which the 177 client obtains the assertion (prior to sending it to the 178 authorization server), there are two common patterns described below. 180 In the first pattern, depicted in Figure 1, the client obtains an 181 assertion from a third party entity capable of issuing, renewing, 182 transforming, and validating security tokens. Typically such an 183 entity is known as a "Security Token Service" (STS) or just "Token 184 Service" and a trust relationship (usually manifested in the exchange 185 of some kind of key material) exists between the token service and 186 the relying party. The token service is the assertion issuer; its 187 role is to fulfill requests from clients, which present various 188 credentials, and mint assertions as requested, fill them with 189 appropriate information, and sign them. WS-Trust [OASIS.WS-Trust] is 190 one available standard for requesting security tokens (assertions). 192 Relying 193 Party Client Token Service 194 | | | 195 | | 1) Request Assertion | 196 | |------------------------>| 197 | | | 198 | | 2) Assertion | 199 | |<------------------------| 200 | 3) Assertion | | 201 |<-------------------------| | 202 | | | 203 | 4) OK or Failure | | 204 |------------------------->| | 205 | | | 206 | | | 208 Figure 1: Third Party Created Assertion 210 In the second pattern, depicted in Figure 2, the client creates 211 assertions locally. To sign the assertions, it has to obtain key 212 material: either symmetric keys or asymmetric key pairs. The 213 mechanisms for obtaining this key material are beyond the scope of 214 this specification. 216 Although assertions are usually used to convey identity and security 217 information, self-issued assertions can also serve a different 218 purpose. They can be used to demonstrate knowledge of some secret, 219 such as a client secret, without actually communicating the secret 220 directly in the transaction. In that case, additional information 221 included in the assertion by the client itself will be of limited 222 value to the relying party and, for this reason, only a bare minimum 223 of information is typically included in such an assertion, such as 224 information about issuing and usage conditions. 226 Relying 227 Party Client 228 | | 229 | | 1) Create 230 | | Assertion 231 | |--------------+ 232 | | | 233 | | 2) Assertion | 234 | |<-------------+ 235 | 3) Assertion | 236 |<-------------------------| 237 | | 238 | 4) OK or Failure | 239 |------------------------->| 240 | | 241 | | 243 Figure 2: Self-Issued Assertion 245 Deployments need to determine the appropriate variant to use based on 246 the required level of security, the trust relationship between the 247 entities, and other factors. 249 From the perspective of what must be done by the entity presenting 250 the assertion, there are two general types of assertions: 252 1. Bearer Assertions: Any entity in possession of a bearer assertion 253 (e.g. the bearer) can use it to get access to the associated 254 resources (without demonstrating possession of a cryptographic 255 key). To prevent misuse, bearer assertions need to be protected 256 from disclosure in storage and in transport. A secure 257 communication channel is required between all entities to avoid 258 leaking the assertion to unauthorized parties. 260 2. Holder-of-Key Assertions: To access the associated resources, the 261 entity presenting the assertion must demonstrate possession of 262 additional cryptographic material. The token service thereby 263 binds a key identifier to the assertion and the client has to 264 demonstrate to the relying party that it knows the key 265 corresponding to that identifier when presenting the assertion. 266 This mechanism provides additional security properties. 268 The protocol parameters and processing rules defined in this document 269 are intended to support a client presenting a bearer assertion to an 270 authorization server. The use of holder-of-key assertions are not 271 precluded by this document, but additional protocol details would 272 need to be specified. 274 4. Transporting Assertions 276 This section defines HTTP parameters for transporting assertions 277 during interactions with a token endpoint of an OAuth authorization 278 server. Because requests to the token endpoint result in the 279 transmission of clear-text credentials (in both the HTTP request and 280 response), all requests to the token endpoint MUST use TLS, as 281 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 283 4.1. Using Assertions as Authorization Grants 285 This section defines the use of assertions as authorization grants, 286 based on the definition provided in Section 4.5 of OAuth 2.0 287 [RFC6749]. When using assertions as authorization grants, the client 288 includes the assertion and related information using the following 289 HTTP request parameters: 291 grant_type REQUIRED. The format of the assertion as defined by the 292 authorization server. The value MUST be an absolute URI. 294 assertion REQUIRED. The assertion being used as an authorization 295 grant. Specific serialization of the assertion is defined by 296 profile documents. The serialization MUST be encoded for 297 transport within HTTP forms. It is RECOMMENDED that base64url be 298 used. 300 scope OPTIONAL. The requested scope as described in Section 3.3 of 301 OAuth 2.0 [RFC6749]. When exchanging assertions for access 302 tokens, the authorization for the token has been previously 303 granted through some out-of-band mechanism. As such, the 304 requested scope MUST be equal or lesser than the scope originally 305 granted to the authorized accessor. If the scope parameter and/or 306 value are omitted, the scope MUST be treated as equal to the scope 307 originally granted to the authorized accessor. The Authorization 308 Server MUST limit the scope of the issued access token to be equal 309 or lesser than the scope originally granted to the authorized 310 accessor. 312 The following non-normative example demonstrates an assertion being 313 used as an authorization grant (with extra line breaks for display 314 purposes only): 316 POST /token HTTP/1.1 317 Host: server.example.com 318 Content-Type: application/x-www-form-urlencoded 320 client_id=s6BhdRkqt3& 321 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 322 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 324 An assertion used in this context is generally a short lived 325 representation of the authorization grant and authorization servers 326 SHOULD NOT issue access tokens with a lifetime that exceeds the 327 validity period of the assertion by a significant period. In 328 practice, that will usually mean that refresh tokens are not issued 329 in response to assertion grant requests and access tokens will be 330 issued with a reasonably short lifetime. Clients can refresh an 331 expired access token by requesting a new one using the same 332 assertion, if it is still valid, or with a new assertion. 334 An IEFT URN for use as the "grant_type" value can be requested using 335 the template in An IETF URN Sub-Namespace for OAuth [RFC6755]. A URN 336 of the form urn:ietf:params:oauth:grant_type:* is suggested. 338 4.1.1. Error Responses 340 If an assertion is not valid or has expired, the Authorization Server 341 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 342 The value of the "error" parameter MUST be the "invalid_grant" error 343 code. The authorization server MAY include additional information 344 regarding the reasons the assertion was considered invalid using the 345 "error_description" or "error_uri" parameters. 347 For example: 349 HTTP/1.1 400 Bad Request 350 Content-Type: application/json 351 Cache-Control: no-store 353 { 354 "error":"invalid_grant", 355 "error_description":"Audience validation failed" 356 } 358 4.2. Using Assertions for Client Authentication 360 The following section defines the use of assertions as client 361 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 362 When using assertions as client credentials, the client includes the 363 assertion and related information using the following HTTP request 364 parameters: 366 client_id OPTIONAL. The client identifier as described in Section 367 2.2 of OAuth 2.0 [RFC6749]. When present, the "client_id" MUST 368 identify the client to the authorization server. 370 client_assertion_type REQUIRED. The format of the assertion as 371 defined by the authorization server. The value MUST be an 372 absolute URI. 374 client_assertion REQUIRED. The assertion being used to authenticate 375 the client. Specific serialization of the assertion is defined by 376 profile documents. The serialization MUST be encoded for 377 transport within HTTP forms. It is RECOMMENDED that base64url be 378 used. 380 The following non-normative example demonstrates a client 381 authenticating using an assertion during an Access Token Request, as 382 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 383 breaks for display purposes only): 385 POST /token HTTP/1.1 386 Host: server.example.com 387 Content-Type: application/x-www-form-urlencoded 389 grant_type=authorization_code& 390 code=i1WsRn1uB1& 391 client_id=s6BhdRkqt3& 392 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 393 %3Aclient-assertion-type%3Asaml2-bearer& 394 client_assertion=PHNhbW...[omitted for brevity]...ZT 396 Token endpoints can differentiate between assertion based credentials 397 and other client credential types by looking for the presence of the 398 "client_assertion" and "client_assertion_type" parameters, which will 399 only be present when using assertions for client authentication. 401 An IEFT URN for use as the "client_assertion_type" value may be 402 requested using the template in An IETF URN Sub-Namespace for OAuth 403 [RFC6755]. A URN of the form 404 urn:ietf:params:oauth:client-assertion-type:* is suggested. 406 4.2.1. Error Responses 408 If an assertion is invalid for any reason or if more than one client 409 authentication mechanism is used, the Authorization Server MUST 410 construct an error response as defined in OAuth 2.0 [RFC6749]. The 411 value of the "error" parameter MUST be the "invalid_client" error 412 code. The authorization server MAY include additional information 413 regarding the reasons the client assertion was considered invalid 414 using the "error_description" or "error_uri" parameters. 416 For example: 418 HTTP/1.1 400 Bad Request 419 Content-Type: application/json 420 Cache-Control: no-store 422 { 423 "error":"invalid_client" 424 "error_description":"assertion has expired" 425 } 427 5. Assertion Content and Processing 429 This section provides a general content and processing model for the 430 use of assertions in OAuth 2.0 [RFC6749]. 432 5.1. Assertion Metamodel 434 The following are entities and metadata involved in the issuance, 435 exchange, and processing of assertions in OAuth 2.0. These are 436 general terms, abstract from any particular assertion format. 437 Mappings of these terms into specific representations are provided by 438 profiles of this specification. 440 Issuer The unique identifier for the entity that issued the 441 assertion. Generally this is the entity that holds the key 442 material used to generate the assertion. Examples of issuers are 443 OAuth clients (when assertions are self-issued) and third party 444 security token services. 446 Principal A unique identifier for the subject of the assertion. 447 When using assertions for client authentication, the Principal 448 SHOULD be the "client_id" of the OAuth client. When using 449 assertions as an authorization grant, the Principal MUST identify 450 an authorized accessor for which the access token is being 451 requested (typically the resource owner, or an authorized 452 delegate). 454 Audience A value that identifies the parties intended to process the 455 assertion. An audience value MAY be the URL of the Token Endpoint 456 as defined in Section 3.2 of OAuth 2.0 [RFC6749]. 458 Issued At The time at which the assertion was issued. While the 459 serialization may differ by assertion format, this is always 460 expressed in UTC with no time zone component. 462 Expires At The time at which the assertion expires. While the 463 serialization may differ by assertion format, this is always 464 expressed in UTC with no time zone component. 466 Assertion ID A nonce or unique identifier for the assertion. The 467 Assertion ID may be used by implementations requiring message de- 468 duplication for one-time use assertions. Any entity that assigns 469 an identifier MUST ensure that there is negligible probability 470 that that entity or any other entity will accidentally assign the 471 same identifier to a different data object. 473 5.2. General Assertion Format and Processing Rules 475 The following are general format and processing rules for the use of 476 assertions in OAuth: 478 o The assertion MUST contain an Issuer. The Issuer MUST identify 479 the entity that issued the assertion as recognized by the 480 Authorization Server. If an assertion is self-issued, the Issuer 481 SHOULD be the "client_id". 483 o The assertion SHOULD contain a Principal. The Principal MUST 484 identify an authorized accessor for which the access token is 485 being requested (typically the resource owner, or an authorized 486 delegate). When the client is acting on behalf of itself, the 487 Principal SHOULD be the "client_id". 489 o The assertion MUST contain an Audience that identifies the 490 Authorization Server as the intended audience. The Authorization 491 Server MUST verify that it is an intended audience for the 492 assertion. The Audience SHOULD be the URL of the Authorization 493 Server's Token Endpoint. 495 o The assertion MUST contain an Expires At entity that limits the 496 time window during which the assertion can be used. The 497 authorization server MUST verify that the expiration time has not 498 passed, subject to allowable clock skew between systems. The 499 authorization server SHOULD reject assertions with an Expires At 500 attribute value that is unreasonably far in the future. 502 o The assertion MAY contain an Issued At entity containing the UTC 503 time at which the assertion was issued. 505 o The assertion MAY contain an Assertion ID. An Authorization 506 Server MAY dictate that Assertion ID is mandatory. 508 o The Authorization Server MUST validate the assertion's signature 509 to verify the Issuer of the assertion. The algorithm used to 510 validate the signature, and the mechanism for designating the 511 secret used to generate the assertion, are beyond the scope of 512 this specification. 514 6. Specific Assertion Format and Processing Rules 516 The following clarifies the format and processing rules defined in 517 Section 4 and Section 5 for a number of common use cases: 519 6.1. Client Authentication 521 When a client uses an assertion for authentication, it SHOULD do so 522 according to Section 4.2. The following format and processing rules 523 apply: 525 o The "client_assertion_type" HTTP parameter MUST identify the 526 assertion format being used for authentication. 528 o The "client_assertion" HTTP parameter MUST contain the serialized 529 assertion in a format indicated by the "client_assertion_type" 530 parameter. 532 o The Principal SHOULD be the "client_id". 534 o The Issuer of the assertion MUST identify the entity that issued 535 the assertion as recognized by the Authorization Server. If the 536 assertion is self-issued, the Issuer SHOULD be the "client_id". 538 o The Audience of the assertion MUST identify the Authorization 539 Server and SHOULD be the URL of the Token Endpoint. 541 o The Authorization Server MUST verify the assertion's signature or 542 keyed message digest to determine the validity of the issuer and 543 the content of the assertion. 545 The following non-normative example demonstrates a client 546 authentication using an assertion during an Access Token Request, as 547 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 548 breaks for display purposes only): 550 POST /token HTTP/1.1 551 Host: server.example.com 552 Content-Type: application/x-www-form-urlencoded 554 grant_type=authorization_code& 555 code=i1WsRn1uB1& 556 client_id=s6BhdRkqt3& 557 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 558 %3Aclient-assertion-type%3Asaml2-bearer& 559 client_assertion=PHNhb...[omitted for brevity]...ZT4 561 6.2. Client Acting on Behalf of Itself 563 When a client is accessing resources on behalf of itself, it SHOULD 564 do so in a manner analogous to the Client Credentials flow defined in 565 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 566 combines both the authentication and authorization grant usage 567 patterns. In this case, the interactions with the authorization 568 server SHOULD be treated as using an assertion for Client 569 Authentication according to Section 4.2, with the addition of a 570 grant_type parameter. The following format and processing rules 571 apply: 573 o The grant_type HTTP request parameter MUST be 574 "client_credentials". 576 o The "client_assertion_type" HTTP parameter MUST identify the 577 assertion format. 579 o The "client_assertion" HTTP parameter MUST contain the serialized 580 assertion as in a format indicated by the "client_assertion_type" 581 parameter. 583 o The Issuer of the assertion MUST identify the entity that issued 584 the assertion as recognized by the Authorization Server. If the 585 assertion is self-issued, the Issuer SHOULD be the "client_id". 586 If the assertion was issued by a Security Token Service (STS), the 587 Issuer SHOULD identify the STS as recognized by the Authorization 588 Server. 590 o The Principal SHOULD be the "client_id". 592 o The Audience of the assertion MUST identify the Authorization 593 Server and SHOULD be the URL of the Token Endpoint. 595 o The Authorization Server MUST validate the assertion's signature 596 to verify the Issuer of the assertion. 598 The following non-normative example demonstrates an assertion being 599 used for a Client Credentials Access Token Request, as defined in 600 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 601 display purposes only): 603 POST /token HTTP/1.1 604 Host: server.example.com 605 Content-Type: application/x-www-form-urlencoded 607 client_id=s6BhdRkqt3& 608 grant_type=client_credentials& 609 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 610 %3Aclient-assertion-type%3Asaml2-bearer& 611 client_assertion=PHNhbW...[omitted for brevity]...ZT 613 6.3. Client Acting on Behalf of a User 615 When a client is accessing resources on behalf of a user, it SHOULD 616 be treated as using an assertion as an Authorization Grant according 617 to Section 4.1. The following format and processing rules apply: 619 o The grant_type HTTP request parameter MUST indicate the assertion 620 format. 622 o The assertion HTTP parameter MUST contain the serialized assertion 623 as in a format indicated by the grant_type parameter. 625 o The Issuer of the assertion MUST identify the entity that issued 626 the assertion as recognized by the Authorization Server. If the 627 assertion is self-issued, the Issuer SHOULD be the "client_id". 628 If the assertion was issued by a Security Token Service (STS), the 629 Issuer SHOULD identify the STS as recognized by the Authorization 630 Server. 632 o The Principal MUST identify an authorized accessor for which the 633 access token is being requested (typically the resource owner, or 634 an authorized delegate). 636 o The Audience of the assertion MUST identify the Authorization 637 Server and MAY be the URL of the Token Endpoint. 639 o The Authorization Server MUST validate the assertion's signature 640 to verify the Issuer of the assertion. 642 The following non-normative example demonstrates a client using an 643 assertion as an Authorization Grant during an Access Token Request, 644 as defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 645 breaks for display purposes only): 647 POST /token HTTP/1.1 648 Host: server.example.com 649 Content-Type: application/x-www-form-urlencoded 651 client_id=s6BhdRkqt3& 652 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 653 assertion=PHNhbWxwOl...[omitted for brevity]...ZT 655 6.4. Client Acting on Behalf of an Anonymous User 657 When a client is accessing resources on behalf of an anonymous user, 658 the following format and processing rules apply: 660 o The grant_type HTTP request parameter MUST indicate the assertion 661 format. 663 o The assertion HTTP parameter MUST contain the serialized assertion 664 as in a format indicated by the grant_type parameter. 666 o The Issuer of the assertion MUST identify the entity that issued 667 the assertion as recognized by the Authorization Server. If the 668 assertion is self-issued, the Issuer SHOULD be the "client_id". 669 If the assertion was issued by a Security Token Service (STS), the 670 Issuer SHOULD identify the STS as recognized by the Authorization 671 Server. 673 o The Principal SHOULD indicate to the Authorization Server that the 674 client is acting on-behalf of an anonymous user as defined by the 675 Authorization Server. It is implied that authorization is based 676 upon additional criteria, such as additional attributes or claims 677 provided in the assertion. For example, a client may present an 678 assertion from a trusted issuer asserting that the bearer is over 679 18 via an included claim. In this case, no additional information 680 about the user's identity is included yet all the data needed to 681 issue an access token is present. 683 o The Audience of the assertion MUST identify the Authorization 684 Server and MAY be the URL of the Token Endpoint. 686 o The Authorization Server MUST validate the assertion's signature 687 to verify the Issuer of the assertion. 689 7. Security Considerations 691 This section discusses security considerations that apply when using 692 assertions with OAuth 2.0 as described in this document. As 693 discussed in Section 3, there are two different ways to obtain 694 assertions: either as self-issued or obtained from a third party 695 token service. While the actual interactions for obtaining an 696 assertion are outside the scope of this document, the details are 697 important from a security perspective. Section 3 discusses the high 698 level architectural aspects. Many of the security considerations 699 discussed in this section are applicable to both the OAuth exchange 700 as well as the client obtaining the assertion. 702 The remainder of this section focuses on the exchanges that concern 703 presenting an assertion for client authentication and for the 704 authorization grant. 706 7.1. Forged Assertion 708 Threat: 709 An adversary could forge or alter an assertion in order to obtain 710 an access token (in case of the authorization grant) or to 711 impersonate a client (in case of the client authentication 712 mechanism). 714 Countermeasures: 715 To avoid this kind of attack, the entities must assure that proper 716 mechanisms for protecting the integrity of the assertion are 717 employed. This includes the issuer digitally signing the 718 assertion or computing a keyed message digest over the assertion. 720 7.2. Stolen Assertion 722 Threat: 723 An adversary may be able obtain an assertion (e.g., by 724 eavesdropping) and then reuse it (replay it) at a later point in 725 time. 727 Countermeasures: 728 The primary mitigation for this threat is the use of a secure 729 communication channel with server authentication for all network 730 exchanges. 732 An assertion may also contain several elements to prevent replay 733 attacks. There is, however, a clear tradeoff between reusing an 734 assertion for multiple exchanges and obtaining and creating new 735 fresh assertions. 737 Authorization Servers and Resource Servers may use a combination 738 of the Assertion ID and Issued At/Expires At attributes for replay 739 protection. Previously processed assertions may be rejected based 740 on the Assertion ID. The addition of the validity window relieves 741 the authorization server from maintaining an infinite state table 742 of processed assertion IDs. 744 7.3. Unauthorized Disclosure of Personal Information 746 Threat: 747 The ability for other entities to obtain information about an 748 individual, such as authentication information, role in an 749 organization, or other authorization relevant information, raises 750 privacy concerns. 752 Countermeasures: 753 To address the threats, two cases need to be differentiated: 755 First, a third party that did not participate in any of the 756 exchange is prevented from eavesdropping on the content of the 757 assertion by employing confidentiality protection of the exchange 758 using TLS. This ensures that an eavesdropper on the wire is 759 unable to obtain information. However, this does not prevent 760 legitimate protocol entities from obtaining information from an 761 assertion they may not have been allowed to obtain. Some 762 assertion formats allow for the assertion to be encrypted, 763 preventing unauthorized parties from inspecting the content. 765 Second, an Authorization Server may obtain an assertion that was 766 created by a third party token service and that token service may 767 have placed attributes into the assertion. To mitigate potential 768 privacy problems, prior consent from the resource owner has to be 769 obtained. OAuth itself does not directly provide such 770 capabilities, but this consent approval may be obtained using 771 other identity management protocols, user consent interactions, or 772 in an out-of-band fashion. 774 For the cases where a third party token service creates assertions 775 to be used for client authentication, privacy concerns are 776 typically lower, since many of these clients are Web servers 777 rather than individual devices operated by humans. If the 778 assertions are used for client authentication of devices or 779 software that can be closely linked to end users, then privacy 780 protection safeguards need to be taken into consideration. 782 Further guidance on privacy friendly protocol design can be found 783 in [I-D.iab-privacy-considerations]. 785 8. IANA Considerations 787 This is a request to add three values, as listed in the sub-sections 788 below, to the "OAuth Parameters" registry established by RFC 6749. 789 [RFC6749] 791 8.1. assertion Parameter Registration 793 o Parameter name: assertion 795 o Parameter usage location: token request 797 o Change controller: IETF 799 o Specification document(s): [[this document]] 801 8.2. client_assertion Parameter Registration 803 o Parameter name: client_assertion 805 o Parameter usage location: token request 807 o Change controller: IETF 809 o Specification document(s): [[this document]] 811 8.3. client_assertion_type Parameter Registration 813 o Parameter name: client_assertion_type 815 o Parameter usage location: token request 817 o Change controller: IETF 819 o Specification document(s): [[this document]] 821 9. References 823 9.1. Normative References 825 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 826 Requirement Levels", BCP 14, RFC 2119, March 1997. 828 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 829 RFC 6749, October 2012. 831 9.2. Informative References 833 [I-D.iab-privacy-considerations] 834 Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 835 Morris, J., Hansen, M., and R. Smith, "Privacy 836 Considerations for Internet Protocols", 837 draft-iab-privacy-considerations-03 (work in progress), 838 July 2012. 840 [I-D.ietf-oauth-jwt-bearer] 841 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 842 (JWT) Bearer Token Profiles for OAuth 2.0", 843 draft-ietf-oauth-jwt-bearer-03 (work in progress), 844 November 2012. 846 [I-D.ietf-oauth-saml2-bearer] 847 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 848 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-15 849 (work in progress), November 2012. 851 [OASIS.WS-Trust] 852 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 853 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", 854 Feb 2009. 856 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 857 for OAuth", RFC 6755, October 2012. 859 Appendix A. Acknowledgements 861 The authors wish to thank the following people that have influenced 862 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 863 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 864 specification, and the members of the OAuth working group. 866 Appendix B. Document History 868 [[ to be removed by the RFC editor before publication as an RFC ]] 870 -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 -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 985 Michael B. Jones 986 Microsoft 988 Email: mbj@microsoft.com 990 Yaron Y. Goland 991 Microsoft 993 Email: yarong@microsoft.com