idnits 2.17.1 draft-ietf-oauth-assertions-07.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 (November 7, 2012) is 4180 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 Summary: 0 errors (**), 0 flaws (~~), 2 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: May 11, 2013 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 November 7, 2012 11 Assertion Framework for OAuth 2.0 12 draft-ietf-oauth-assertions-07 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 May 11, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 19 89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 90 9.2. Informative References . . . . . . . . . . . . . . . . . . 19 91 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 92 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 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. 126 Note: The use of assertions for client authentication is orthogonal 127 to and separable from using assertions as an authorization grant. 128 They can be used either in combination or separately. Client 129 assertion authentication is nothing more than an alternative way for 130 a client to authenticate to the token endpoint and must be used in 131 conjunction with some grant type to form a complete and meaningful 132 protocol request. Assertion authorization grants may be used with or 133 without client authentication or identification. Whether or not 134 client authentication is needed in conjunction with an assertion 135 authorization grant, as well as the supported types of client 136 authentication, are policy decisions at the discretion of the 137 authorization server. 139 2. Terminology 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in [RFC2119] . 145 Throughout this document, values are quoted to indicate that they are 146 to be taken literally. When using these values in protocol messages, 147 the quotes must not be used as part of the value. 149 3. Framework 151 An assertion is a package of information that allows identity and 152 security information to be shared across security domains. An 153 assertion typically contains information about a subject or 154 principal, information about the party that issued the assertion and 155 when was it issued, as well as the conditions under which the 156 assertion is to be considered valid, such as when and where it can be 157 used. 159 The entity that creates and signs the assertion is typically known as 160 the "Issuer" and the entity that consumes the assertion and relies on 161 its information is typically known as the "Relying Party". In the 162 context of this document, the authorization server acts as a relying 163 party. 165 Assertions used in the protocol exchanges defined by this 166 specification MUST always be protected against tampering using a 167 digital signature or a keyed message digest applied by the issuer. 168 An assertion MAY additionally be encrypted, preventing unauthorized 169 parties from inspecting the content. 171 Although this document does not define the processes by which the 172 client obtains the assertion (prior to sending it to the 173 authorization server), there are two common patterns described below. 175 In the first pattern, depicted in Figure 1, the client obtains an 176 assertion from a third party entity capable of issuing, renewing, 177 transforming, and validating security tokens. Typically such an 178 entity is known as a "Security Token Service" (STS) or just "Token 179 Service" and a trust relationship (usually manifested in the exchange 180 of some kind of key material) exists between the token service and 181 the relying party. The token service is the assertion issuer; its 182 role is to fulfill requests from clients, which present various 183 credentials, and mint assertions as requested, fill them with 184 appropriate information, and sign them. WS-Trust [OASIS.WS-Trust] is 185 one available standard for requesting security tokens (assertions). 187 Relying 188 Party Client Token Service 189 | | | 190 | | 1) Request Assertion | 191 | |------------------------>| 192 | | | 193 | | 2) Assertion | 194 | |<------------------------| 195 | 3) Assertion | | 196 |<-------------------------| | 197 | | | 198 | 4) OK or Failure | | 199 |------------------------->| | 200 | | | 201 | | | 203 Figure 1: Third Party Created Assertion 205 In the second pattern, depicted in Figure 2, the client creates 206 assertions locally. To sign the assertions, it has to obtain key 207 material: either symmetric keys or asymmetric key pairs. The 208 mechanisms for obtaining this key material are beyond the scope of 209 this specification. 211 Although assertions are usually used to convey identity and security 212 information, self-issued assertions can also serve a different 213 purpose. They can be used to demonstrate knowledge of some secret, 214 such as a client secret, without actually communicating the secret 215 directly in the transaction. In that case, additional information 216 included in the assertion by the client itself will be of limited 217 value to the relying party and, for this reason, only a bare minimum 218 of information is typically included in such an assertion, such as 219 information about issuing and usage conditions. 221 Relying 222 Party Client 223 | | 224 | | 1) Create 225 | | Assertion 226 | |--------------+ 227 | | | 228 | | 2) Assertion | 229 | |<-------------+ 230 | 3) Assertion | 231 |<-------------------------| 232 | | 233 | 4) OK or Failure | 234 |------------------------->| 235 | | 236 | | 238 Figure 2: Self-Issued Assertion 240 Deployments need to determine the appropriate variant to use based on 241 the required level of security, the trust relationship between the 242 entities, and other factors. 244 From the perspective of what must be done by the entity presenting 245 the assertion, there are two general types of assertions: 247 1. Bearer Assertions: Any entity in possession of a bearer assertion 248 (e.g. the bearer) can use it to get access to the associated 249 resources (without demonstrating possession of a cryptographic 250 key). To prevent misuse, bearer assertions need to be protected 251 from disclosure in storage and in transport. A secure 252 communication channel is required between all entities to avoid 253 leaking the assertion to unauthorized parties. 255 2. Holder-of-Key Assertions: To access the associated resources, the 256 entity presenting the assertion must demonstrate possession of 257 additional cryptographic material. The token service thereby 258 binds a key identifier to the assertion and the client has to 259 demonstrate to the relying party that it knows the key 260 corresponding to that identifier when presenting the assertion. 261 This mechanism provides additional security properties. 263 The protocol parameters and processing rules defined in this document 264 are intended to support a client presenting a bearer assertion to an 265 authorization server. The use of holder-of-key assertions are not 266 precluded by this document, but additional protocol details would 267 need to be specified. 269 4. Transporting Assertions 271 This section defines HTTP parameters for transporting assertions 272 during interactions with a token endpoint of an OAuth authorization 273 server. Because requests to the token endpoint result in the 274 transmission of clear-text credentials (in both the HTTP request and 275 response), all requests to the token endpoint MUST use TLS, as 276 mandated in Section 3.2 of OAuth 2.0 [RFC6749]. 278 4.1. Using Assertions as Authorization Grants 280 This section defines the use of assertions as authorization grants, 281 based on the definition provided in Section 4.5 of OAuth 2.0 282 [RFC6749]. When using assertions as authorization grants, the client 283 includes the assertion and related information using the following 284 HTTP request parameters: 286 grant_type REQUIRED. The format of the assertion as defined by the 287 authorization server. The value MUST be an absolute URI. 289 assertion REQUIRED. The assertion being used as an authorization 290 grant. Specific serialization of the assertion is defined by 291 profile documents. The serialization MUST be encoded for 292 transport within HTTP forms. It is RECOMMENDED that base64url be 293 used. 295 scope OPTIONAL. The requested scope as described in Section 3.3 of 296 OAuth 2.0 [RFC6749]. When exchanging assertions for access 297 tokens, the authorization for the token has been previously 298 granted through some out-of-band mechanism. As such, the 299 requested scope MUST be equal or lesser than the scope originally 300 granted to the authorized accessor. If the scope parameter and/or 301 value are omitted, the scope MUST be treated as equal to the scope 302 originally granted to the authorized accessor. The Authorization 303 Server MUST limit the scope of the issued access token to be equal 304 or lesser than the scope originally granted to the authorized 305 accessor. 307 The following non-normative example demonstrates an assertion being 308 used as an authorization grant (with extra line breaks for display 309 purposes only): 311 POST /token HTTP/1.1 312 Host: server.example.com 313 Content-Type: application/x-www-form-urlencoded 315 client_id=s6BhdRkqt3& 316 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 317 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 319 An assertion used in this context is generally a short lived 320 representation of the authorization grant and authorization servers 321 SHOULD NOT issue access tokens with a lifetime that exceeds the 322 validity period of the assertion by a significant period. In 323 practice, that will usually mean that refresh tokens are not issued 324 in response to assertion grant requests and access tokens will be 325 issued with a reasonably short lifetime. Clients can refresh an 326 expired access token by requesting a new one using the same 327 assertion, if it is still valid, or with a new assertion. 329 An IEFT URN for use as the "grant_type" value can be requested using 330 the template in An IETF URN Sub-Namespace for OAuth 331 [I-D.ietf-oauth-urn-sub-ns]. A URN of the form 332 urn:ietf:params:oauth:grant_type:* is suggested. 334 4.1.1. Error Responses 336 If an assertion is not valid or has expired, the Authorization Server 337 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 338 The value of the "error" parameter MUST be the "invalid_grant" error 339 code. The authorization server MAY include additional information 340 regarding the reasons the assertion was considered invalid using the 341 "error_description" or "error_uri" parameters. 343 For example: 345 HTTP/1.1 400 Bad Request 346 Content-Type: application/json 347 Cache-Control: no-store 349 { 350 "error":"invalid_grant", 351 "error_description":"Audience validation failed" 352 } 354 4.2. Using Assertions for Client Authentication 356 The following section defines the use of assertions as client 357 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 358 When using assertions as client credentials, the client includes the 359 assertion and related information using the following HTTP request 360 parameters: 362 client_id OPTIONAL. The client identifier as described in Section 363 2.2 of OAuth 2.0 [RFC6749]. When present, the "client_id" MUST 364 identify the client to the authorization server. 366 client_assertion_type REQUIRED. The format of the assertion as 367 defined by the authorization server. The value MUST be an 368 absolute URI. 370 client_assertion REQUIRED. The assertion being used to authenticate 371 the client. Specific serialization of the assertion is defined by 372 profile documents. The serialization MUST be encoded for 373 transport within HTTP forms. It is RECOMMENDED that base64url be 374 used. 376 The following non-normative example demonstrates a client 377 authenticating using an assertion during an Access Token Request, as 378 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 379 breaks for display purposes only): 381 POST /token HTTP/1.1 382 Host: server.example.com 383 Content-Type: application/x-www-form-urlencoded 385 grant_type=authorization_code& 386 code=i1WsRn1uB1& 387 client_id=s6BhdRkqt3& 388 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 389 %3Aclient-assertion-type%3Asaml2-bearer& 390 client_assertion=PHNhbW...[omitted for brevity]...ZT 392 Token endpoints can differentiate between assertion based credentials 393 and other client credential types by looking for the presence of the 394 "client_assertion" and "client_assertion_type" parameters, which will 395 only be present when using assertions for client authentication. 397 An IEFT URN for use as the "client_assertion_type" value may be 398 requested using the template in An IETF URN Sub-Namespace for OAuth 399 [I-D.ietf-oauth-urn-sub-ns]. A URN of the form 400 urn:ietf:params:oauth:client-assertion-type:* is suggested. 402 4.2.1. Error Responses 404 If an assertion is invalid for any reason or if more than one client 405 authentication mechanism is used, the Authorization Server MUST 406 construct an error response as defined in OAuth 2.0 [RFC6749]. The 407 value of the "error" parameter MUST be the "invalid_client" error 408 code. The authorization server MAY include additional information 409 regarding the reasons the client assertion was considered invalid 410 using the "error_description" or "error_uri" parameters. 412 For example: 414 HTTP/1.1 400 Bad Request 415 Content-Type: application/json 416 Cache-Control: no-store 418 { 419 "error":"invalid_client" 420 "error_description":"assertion has expired" 421 } 423 5. Assertion Content and Processing 425 This section provides a general content and processing model for the 426 use of assertions in OAuth 2.0 [RFC6749]. 428 5.1. Assertion Metamodel 430 The following are entities and metadata involved in the issuance, 431 exchange, and processing of assertions in OAuth 2.0. These are 432 general terms, abstract from any particular assertion format. 433 Mappings of these terms into specific representations are provided by 434 profiles of this specification. 436 Issuer The unique identifier for the entity that issued the 437 assertion. Generally this is the entity that holds the key 438 material used to generate the assertion. The issuer may be either 439 an OAuth client (when assertions are self-issued) or a third party 440 token service. 442 Principal A unique identifier for the subject of the assertion. 443 When using assertions for client authentication, the Principal 444 SHOULD be the "client_id" of the OAuth client. When using 445 assertions as an authorization grant, the Principal MUST identify 446 an authorized accessor for which the access token is being 447 requested (typically the resource owner, or an authorized 448 delegate). 450 Audience A URI that identifies the party intended to process the 451 assertion. The audience SHOULD be the URL of the Token Endpoint 452 as defined in Section 3.2 of OAuth 2.0 [RFC6749]. 454 Issued At The time at which the assertion was issued. While the 455 serialization may differ by assertion format, this is always 456 expressed in UTC with no time zone component. 458 Expires At The time at which the assertion expires. While the 459 serialization may differ by assertion format, this is always 460 expressed in UTC with no time zone component. 462 Assertion ID A nonce or unique identifier for the assertion. The 463 Assertion ID may be used by implementations requiring message de- 464 duplication for one-time use assertions. Any entity that assigns 465 an identifier MUST ensure that there is negligible probability 466 that that entity or any other entity will accidentally assign the 467 same identifier to a different data object. 469 5.2. General Assertion Format and Processing Rules 471 The following are general format and processing rules for the use of 472 assertions in OAuth: 474 o The assertion MUST contain an Issuer. The Issuer MUST identify 475 the entity that issued the assertion as recognized by the 476 Authorization Server. If an assertion is self-issued, the Issuer 477 SHOULD be the "client_id". 479 o The assertion SHOULD contain a Principal. The Principal MUST 480 identify an authorized accessor for which the access token is 481 being requested (typically the resource owner, or an authorized 482 delegate). When the client is acting on behalf of itself, the 483 Principal SHOULD be the "client_id". 485 o The assertion MUST contain an Audience that identifies the 486 Authorization Server as the intended audience. The Authorization 487 Server MUST verify that it is an intended audience for the 488 assertion. The Audience SHOULD be the URL of the Authorization 489 Server's Token Endpoint. 491 o The assertion MUST contain an Expires At entity that limits the 492 time window during which the assertion can be used. The 493 authorization server MUST verify that the expiration time has not 494 passed, subject to allowable clock skew between systems. The 495 authorization server SHOULD reject assertions with an Expires At 496 attribute value that is unreasonably far in the future. 498 o The assertion MAY contain an Issued At entity containing the UTC 499 time at which the assertion was issued. 501 o The assertion MAY contain an Assertion ID. An Authorization 502 Server MAY dictate that Assertion ID is mandatory. 504 o The Authorization Server MUST validate the assertion's signature 505 to verify the Issuer of the assertion. The algorithm used to 506 validate the signature, and the mechanism for designating the 507 secret used to generate the assertion, are beyond the scope of 508 this specification. 510 6. Specific Assertion Format and Processing Rules 512 The following clarifies the format and processing rules defined in 513 Section 4 and Section 5 for a number of common use cases: 515 6.1. Client Authentication 517 When a client uses an assertion for authentication, it SHOULD do so 518 according to Section 4.2. The following format and processing rules 519 apply: 521 o The "client_assertion_type" HTTP parameter MUST identify the 522 assertion format being used for authentication. 524 o The "client_assertion" HTTP parameter MUST contain the serialized 525 assertion in a format indicated by the "client_assertion_type" 526 parameter. 528 o The Principal SHOULD be the "client_id". 530 o The Issuer of the assertion MUST identify the entity that issued 531 the assertion as recognized by the Authorization Server. If the 532 assertion is self-issued, the Issuer SHOULD be the "client_id". 534 o The Audience of the assertion MUST identify the Authorization 535 Server and SHOULD be the URL of the Token Endpoint. 537 o The Authorization Server MUST verify the assertion's signature or 538 keyed message digest to determine the validity of the issuer and 539 the content of the assertion. 541 The following non-normative example demonstrates a client 542 authentication using an assertion during an Access Token Request, as 543 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 544 breaks for display purposes only): 546 POST /token HTTP/1.1 547 Host: server.example.com 548 Content-Type: application/x-www-form-urlencoded 550 grant_type=authorization_code& 551 code=i1WsRn1uB1& 552 client_id=s6BhdRkqt3& 553 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 554 %3Aclient-assertion-type%3Asaml2-bearer& 555 client_assertion=PHNhb...[omitted for brevity]...ZT4 557 6.2. Client Acting on Behalf of Itself 559 When a client is accessing resources on behalf of itself, it SHOULD 560 do so in a manner analogous to the Client Credentials flow defined in 561 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 562 combines both the authentication and authorization grant usage 563 patterns. In this case, the interactions with the authorization 564 server SHOULD be treated as using an assertion for Client 565 Authentication according to Section 4.2, with the addition of a 566 grant_type parameter. The following format and processing rules 567 apply: 569 o The grant_type HTTP request parameter MUST be 570 "client_credentials". 572 o The "client_assertion_type" HTTP parameter MUST identify the 573 assertion format. 575 o The "client_assertion" HTTP parameter MUST contain the serialized 576 assertion as in a format indicated by the "client_assertion_type" 577 parameter. 579 o The Issuer of the assertion MUST identify the entity that issued 580 the assertion as recognized by the Authorization Server. If the 581 assertion is self-issued, the Issuer SHOULD be the "client_id". 582 If the assertion was issued by a Security Token Service (STS), the 583 Issuer SHOULD identify the STS as recognized by the Authorization 584 Server. 586 o The Principal SHOULD be the "client_id". 588 o The Audience of the assertion MUST identify the Authorization 589 Server and SHOULD be the URL of the Token Endpoint. 591 o The Authorization Server MUST validate the assertion's signature 592 to verify the Issuer of the assertion. 594 The following non-normative example demonstrates an assertion being 595 used for a Client Credentials Access Token Request, as defined in 596 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 597 display purposes only): 599 POST /token HTTP/1.1 600 Host: server.example.com 601 Content-Type: application/x-www-form-urlencoded 603 client_id=s6BhdRkqt3& 604 grant_type=client_credentials& 605 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 606 %3Aclient-assertion-type%3Asaml2-bearer& 607 client_assertion=PHNhbW...[omitted for brevity]...ZT 609 6.3. Client Acting on Behalf of a User 611 When a client is accessing resources on behalf of a user, it SHOULD 612 be treated as using an assertion as an Authorization Grant according 613 to Section 4.1. The following format and processing rules apply: 615 o The grant_type HTTP request parameter MUST indicate the assertion 616 format. 618 o The assertion HTTP parameter MUST contain the serialized assertion 619 as in a format indicated by the grant_type parameter. 621 o The Issuer of the assertion MUST identify the entity that issued 622 the assertion as recognized by the Authorization Server. If the 623 assertion is self-issued, the Issuer SHOULD be the "client_id". 624 If the assertion was issued by a Security Token Service (STS), the 625 Issuer SHOULD identify the STS as recognized by the Authorization 626 Server. 628 o The Principal MUST identify an authorized accessor for which the 629 access token is being requested (typically the resource owner, or 630 an authorized delegate). 632 o The Audience of the assertion MUST identify the Authorization 633 Server and MAY be the URL of the Token Endpoint. 635 o The Authorization Server MUST validate the assertion's signature 636 to verify the Issuer of the assertion. 638 The following non-normative example demonstrates a client using an 639 assertion as an Authorization Grant during an Access Token Request, 640 as defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 641 breaks for display purposes only): 643 POST /token HTTP/1.1 644 Host: server.example.com 645 Content-Type: application/x-www-form-urlencoded 647 client_id=s6BhdRkqt3& 648 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 649 assertion=PHNhbWxwOl...[omitted for brevity]...ZT 651 6.4. Client Acting on Behalf of an Anonymous User 653 When a client is accessing resources on behalf of an anonymous user, 654 the following format and processing rules apply: 656 o The grant_type HTTP request parameter MUST indicate the assertion 657 format. 659 o The assertion HTTP parameter MUST contain the serialized assertion 660 as in a format indicated by the grant_type parameter. 662 o The Issuer of the assertion MUST identify the entity that issued 663 the assertion as recognized by the Authorization Server. If the 664 assertion is self-issued, the Issuer SHOULD be the "client_id". 665 If the assertion was issued by a Security Token Service (STS), the 666 Issuer SHOULD identify the STS as recognized by the Authorization 667 Server. 669 o The Principal SHOULD indicate to the Authorization Server that the 670 client is acting on-behalf of an anonymous user as defined by the 671 Authorization Server. It is implied that authorization is based 672 upon additional criteria, such as additional attributes or claims 673 provided in the assertion. For example, a client may present an 674 assertion from a trusted issuer asserting that the bearer is over 675 18 via an included claim. In this case, no additional information 676 about the user's identity is included yet all the data needed to 677 issue an access token is present. 679 o The Audience of the assertion MUST identify the Authorization 680 Server and MAY be the URL of the Token Endpoint. 682 o The Authorization Server MUST validate the assertion's signature 683 to verify the Issuer of the assertion. 685 7. Security Considerations 687 This section discusses security considerations that apply when using 688 assertions with OAuth 2.0 as described in this document. As 689 discussed in Section 3, there are two different ways to obtain 690 assertions: either as self-issued or obtained from a third party 691 token service. While the actual interactions for obtaining an 692 assertion are outside the scope of this document, the details are 693 important from a security perspective. Section 3 discusses the high 694 level architectural aspects. Many of the security considerations 695 discussed in this section are applicable to both the OAuth exchange 696 as well as the client obtaining the assertion. 698 The remainder of this section focuses on the exchanges that concern 699 presenting an assertion for client authentication and for the 700 authorization grant. 702 7.1. Forged Assertion 704 Threat: 705 An adversary could forge or alter an assertion in order to obtain 706 an access token (in case of the authorization grant) or to 707 impersonate a client (in case of the client authentication 708 mechanism). 710 Countermeasures: 711 To avoid this kind of attack, the entities must assure that proper 712 mechanisms for protecting the integrity of the assertion are 713 employed. This includes the issuer digitally signing the 714 assertion or computing a keyed message digest over the assertion. 716 7.2. Stolen Assertion 718 Threat: 719 An adversary may be able obtain an assertion (e.g., by 720 eavesdropping) and then reuse it (replay it) at a later point in 721 time. 723 Countermeasures: 724 The primary mitigation for this threat is the use of a secure 725 communication channel with server authentication for all network 726 exchanges. 728 An assertion may also contain several elements to prevent replay 729 attacks. There is, however, a clear tradeoff between reusing an 730 assertion for multiple exchanges and obtaining and creating new 731 fresh assertions. 733 Authorization Servers and Resource Servers may use a combination 734 of the Assertion ID and Issued At/Expires At attributes for replay 735 protection. Previously processed assertions may be rejected based 736 on the Assertion ID. The addition of the validity window relieves 737 the authorization server from maintaining an infinite state table 738 of processed assertion IDs. 740 7.3. Unauthorized Disclosure of Personal Information 742 Threat: 743 The ability for other entities to obtain information about an 744 individual, such as authentication information, role in an 745 organization, or other authorization relevant information, raises 746 privacy concerns. 748 Countermeasures: 749 To address the threats, two cases need to be differentiated: 751 First, a third party that did not participate in any of the 752 exchange is prevented from eavesdropping on the content of the 753 assertion by employing confidentiality protection of the exchange 754 using TLS. This ensures that an eavesdropper on the wire is 755 unable to obtain information. However, this does not prevent 756 legitimate protocol entities from obtaining information from an 757 assertion they may not have been allowed to obtain. Some 758 assertion formats allow for the assertion to be encrypted, 759 preventing unauthorized parties from inspecting the content. 761 Second, an Authorization Server may obtain an assertion that was 762 created by a third party token service and that token service may 763 have placed attributes into the assertion. To mitigate potential 764 privacy problems, prior consent from the resource owner has to be 765 obtained. OAuth itself does not directly provide such 766 capabilities, but this consent approval may be obtained using 767 other identity management protocols, user consent interactions, or 768 in an out-of-band fashion. 770 For the cases where a third party token service creates assertions 771 to be used for client authentication, privacy concerns are 772 typically lower, since many of these clients are Web servers 773 rather than individual devices operated by humans. If the 774 assertions are used for client authentication of devices or 775 software that can be closely linked to end users, then privacy 776 protection safeguards need to be taken into consideration. 778 Further guidance on privacy friendly protocol design can be found 779 in [I-D.iab-privacy-considerations]. 781 8. IANA Considerations 783 8.1. assertion Parameter Registration 785 The following is the parameter registration request, as defined in 786 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 787 [RFC6749], for the "assertion" parameter: 789 o Parameter name: assertion 791 o Parameter usage location: token request 793 o Change controller: IETF 795 o Specification document(s): [[this document]] 797 8.2. client_assertion Parameter Registration 799 The following is the parameter registration request, as defined in 800 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 801 [RFC6749], for the "client_assertion" parameter: 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 The following is the parameter registration request, as defined in 814 The OAuth Parameters Registry of The OAuth 2.0 Authorization Protocol 815 [RFC6749], for the "client_assertion_type" parameter: 817 o Parameter name: "client_assertion_type" 819 o Parameter usage location: token request 821 o Change controller: IETF 823 o Specification document(s): [[this document]] 825 9. References 826 9.1. Normative References 828 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 829 Requirement Levels", BCP 14, RFC 2119, March 1997. 831 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 832 RFC 6749, October 2012. 834 9.2. Informative References 836 [I-D.iab-privacy-considerations] 837 Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 838 Morris, J., Hansen, M., and R. Smith, "Privacy 839 Considerations for Internet Protocols", 840 draft-iab-privacy-considerations-03 (work in progress), 841 July 2012. 843 [I-D.ietf-oauth-urn-sub-ns] 844 Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 845 for OAuth", draft-ietf-oauth-urn-sub-ns-06 (work in 846 progress), July 2012. 848 [OASIS.WS-Trust] 849 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 850 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", 851 Feb 2009. 853 Appendix A. Acknowledgements 855 The authors wish to thank the following people that have influenced 856 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 857 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 858 specification, and the members of the OAuth working group. 860 Appendix B. Document History 862 [[ to be removed by RFC editor before publication as an RFC ]] 864 draft-ietf-oauth-assertions-07 866 o Reference RFC 6749. 868 o Remove extraneous word per 869 http://www.ietf.org/mail-archive/web/oauth/current/msg10029.html 871 draft-ietf-oauth-assertions-06 872 o Add more text to intro explaining that an assertion grant type can 873 be used with or without client authentication/identification and 874 that client assertion authentication is nothing more than an 875 alternative way for a client to authenticate to the token endpoint 877 draft-ietf-oauth-assertions-05 879 o Non-normative editorial cleanups 881 draft-ietf-oauth-assertions-04 883 o Updated document to incorporate the review comments from the 884 shepherd - thread and alternative draft at 885 http://www.ietf.org/mail-archive/web/oauth/current/msg09437.html 887 o Added reference to draft-ietf-oauth-urn-sub-ns and include 888 suggestions on 889 urn:ietf:params:oauth:[grant-type|client-assertion-type]:* URNs 891 draft-ietf-oauth-assertions-03 893 o updated reference to draft-ietf-oauth-v2 from -25 to -26 895 draft-ietf-oauth-assertions-02 897 o Added text about limited lifetime ATs and RTs per 898 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 900 o Changed the line breaks in some examples to avoid awkward 901 rendering to text format. Also removed encoded '=' padding from a 902 few examples because both known derivative specs, SAML and JWT, 903 omit the padding char in serialization/encoding. 905 o Remove section 7 on error responses and move that (somewhat 906 modified) content into subsections of section 4 broken up by 907 authn/authz per 908 http://www.ietf.org/mail-archive/web/oauth/current/msg08735.html. 910 o Rework the text about "MUST validate ... in order to establish a 911 mapping between ..." per 912 http://www.ietf.org/mail-archive/web/oauth/current/msg08872.html 913 and 914 http://www.ietf.org/mail-archive/web/oauth/current/msg08749.html. 916 o Change "The Principal MUST identify an authorized accessor. If 917 the assertion is self-issued, the Principal SHOULD be the 918 client_id" in 6.1 per 919 http://www.ietf.org/mail-archive/web/oauth/current/msg08873.html. 921 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 922 oauth-v2 (rather than self) 923 http://www.ietf.org/mail-archive/web/oauth/current/msg08874.html. 925 o Move the "Section 3 of" out of the xref to hopefully fix the link 926 in 4.1 and remove the client_id bullet from 4.2 per 927 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 929 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 930 some then redundant text per 931 http://www.ietf.org/mail-archive/web/oauth/current/msg08890.html. 933 o Change "The following format and processing rules SHOULD be 934 applied" to "The following format and processing rules apply" in 935 sections 6.x to remove conflicting normative qualification of 936 other normative statements per 937 http://www.ietf.org/mail-archive/web/oauth/current/msg08892.html. 939 o Add text the client_id must id the client to 4.1 and remove 940 similar text from other places per 941 http://www.ietf.org/mail-archive/web/oauth/current/msg08893.html. 943 o Remove the MUST from the text prior to the HTTP parameter 944 definitions per 945 http://www.ietf.org/mail-archive/web/oauth/current/msg08920.html. 947 o Updated examples to use grant_type and client_assertion_type 948 values from the OAuth SAML Assertion Profiles spec. 950 Authors' Addresses 952 Brian Campbell 953 Ping Identity Corp. 955 Email: brian.d.campbell@gmail.com 957 Chuck Mortimore 958 Salesforce.com 960 Email: cmortimore@salesforce.com 961 Michael B. Jones 962 Microsoft 964 Email: mbj@microsoft.com 966 Yaron Y. Goland 967 Microsoft 969 Email: yarong@microsoft.com