idnits 2.17.1 draft-ietf-oauth-assertions-13.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 9, 2013) is 3784 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 (-30) exists of draft-ietf-oauth-dyn-reg-13 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 Identity 4 Intended status: Standards Track C. Mortimore 5 Expires: June 12, 2014 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 December 9, 2013 11 Assertion Framework for OAuth 2.0 Client Authentication and 12 Authorization Grants 13 draft-ietf-oauth-assertions-13 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 June 12, 2014. 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 4. Transporting Assertions . . . . . . . . . . . . . . . . . . . 7 70 4.1. Using Assertions as Authorization Grants . . . . . . . . 7 71 4.1.1. Error Responses . . . . . . . . . . . . . . . . . . . 8 72 4.2. Using Assertions for Client Authentication . . . . . . . 8 73 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 9 74 5. Assertion Content and Processing . . . . . . . . . . . . . . 10 75 5.1. Assertion Metamodel . . . . . . . . . . . . . . . . . . . 10 76 5.2. General Assertion Format and Processing Rules . . . . . . 11 77 6. Common Scenarios . . . . . . . . . . . . . . . . . . . . . . 12 78 6.1. Client Authentication . . . . . . . . . . . . . . . . . . 12 79 6.2. Client Acting on Behalf of Itself . . . . . . . . . . . . 12 80 6.3. Client Acting on Behalf of a User . . . . . . . . . . . . 13 81 6.3.1. Client Acting on Behalf of an Anonymous User . . . . 13 82 7. Interoperability Considerations . . . . . . . . . . . . . . . 14 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 84 8.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . 15 85 8.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . 15 86 8.3. Unauthorized Disclosure of Personal Information . . . . . 15 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 88 9.1. assertion Parameter Registration . . . . . . . . . . . . 16 89 9.2. client_assertion Parameter Registration . . . . . . . . . 17 90 9.3. client_assertion_type Parameter Registration . . . . . . 17 91 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 92 10.1. Normative References . . . . . . . . . . . . . . . . . . 17 93 10.2. Informative References . . . . . . . . . . . . . . . . . 17 94 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 18 95 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18 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 324 Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the 325 "client_id" is only needed when a form of client authentication that 326 relies on the 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 urn:ietf:params:oauth 351 :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 392 Section 2.2 of OAuth 2.0 [RFC6749]. The "client_id" is 393 unnecessary for client assertion authentication because the client 394 is identified by the subject of the assertion. If present, the 395 value of the "client_id" parameter MUST identify the same client 396 as is 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. In the absence of an application profile specifying 465 otherwise, compliant applications MUST compare Issuer values using 466 the Simple String Comparison method defined in Section 6.2.1 of 467 RFC 3986 [RFC3986]. 469 Subject A unique identifier for the principal that is the subject of 470 the assertion. 472 * When using assertions for client authentication, the Subject 473 identifies the client to the authorization server using the 474 value of the "client_id" of the OAuth client. 476 * When using assertions as an authorization grant, the Subject 477 identifies an authorized accessor for which the access token is 478 being requested (typically the resource owner, or an authorized 479 delegate). 481 Audience A value that identifies the party or parties intended to 482 process the assertion. The URL of the Token Endpoint, as defined 483 in Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate 484 that the authorization server as a valid intended audience of the 485 assertion. In the absence of an application profile specifying 486 otherwise, compliant applications MUST compare the audience values 487 using the Simple String Comparison method defined in Section 6.2.1 488 of RFC 3986 [RFC3986]. 490 Issued At The time at which the assertion was issued. While the 491 serialization may differ by assertion format, it is REQUIRED that 492 the time be expressed in UTC with no time zone component. 494 Expires At The time at which the assertion expires. While the 495 serialization may differ by assertion format, it is REQUIRED that 496 the time be expressed in UTC with no time zone component. 498 Assertion ID A nonce or unique identifier for the assertion. The 499 Assertion ID may be used by implementations requiring message de- 500 duplication for one-time use assertions. Any entity that assigns 501 an identifier MUST ensure that there is negligible probability 502 that that entity or any other entity will accidentally assign the 503 same identifier to a different data object. 505 5.2. General Assertion Format and Processing Rules 507 The following are general format and processing rules for the use of 508 assertions in OAuth: 510 o The assertion MUST contain an Issuer. The Issuer MUST identify 511 the entity that issued the assertion as recognized by the 512 Authorization Server. If an assertion is self-issued, the Issuer 513 MUST be the value of the client's "client_id". 515 o The assertion MUST contain a Subject. The Subject identifies an 516 authorized accessor for which the access token is being requested 517 (typically the resource owner, or an authorized delegate). When 518 the client is acting on behalf of itself, the Subject MUST be the 519 value of the client's "client_id". 521 o The assertion MUST contain an Audience that identifies the 522 Authorization Server as the intended audience. Assertions that do 523 not identify the Authorization Server as an intended audience MUST 524 be rejected. 526 o The assertion MUST contain an Expires At entity that limits the 527 time window during which the assertion can be used. The 528 authorization server MUST reject assertions that have expired 529 (subject to allowable clock skew between systems). The 530 authorization server MAY reject assertions with an Expires At 531 attribute value that is unreasonably far in the future. 533 o The assertion MAY contain an Issued At entity containing the UTC 534 time at which the assertion was issued. 536 o The Authorization Server MUST reject assertions with an invalid 537 signature or keyed message digest. The algorithm used to validate 538 the signature or message authentication code and the mechanism for 539 designating the secret used to generate the signature or message 540 authentication code over the assertion are beyond the scope of 541 this specification. 543 6. Common Scenarios 545 The following provides additional guidance, beyond the format and 546 processing rules defined in Section 4 and Section 5, on assertion use 547 for a number of common use cases. 549 6.1. Client Authentication 551 A client uses an assertion to authenticate to the authorization 552 server's token endpoint by using the "client_assertion_type" and 553 "client_assertion" parameters as defined in Section 4.2. The Subject 554 of the assertion identifies the client. If the assertion is self- 555 issued by the client, the Issuer of the assertion also identifies the 556 client. 558 The example in Section 4.2 that shows a client authenticating using 559 an assertion during an Access Token Request. 561 6.2. Client Acting on Behalf of Itself 563 When a client is accessing resources on behalf of itself, it does so 564 in a manner analogous to the Client Credentials Grant 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, while using the grant_type 570 parameter with the value "client_credentials" to indicate that the 571 client is requesting an access token using only its client 572 credentials. 574 The following non-normative example demonstrates an assertion being 575 used for a Client Credentials Access Token Request, as defined in 576 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 577 display purposes only): 579 POST /token HTTP/1.1 580 Host: server.example.com 581 Content-Type: application/x-www-form-urlencoded 583 grant_type=client_credentials& 584 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 585 %3Aclient-assertion-type%3Asaml2-bearer& 586 client_assertion=PHNhbW...[omitted for brevity]...ZT 588 6.3. Client Acting on Behalf of a User 590 When a client is accessing resources on behalf of a user, it does so 591 by using the "grant_type" and "assertion" parameters as defined in 592 Section 4.1. The Subject identifies an authorized accessor for which 593 the access token is being requested (typically the resource owner, or 594 an authorized delegate). 596 The example in Section 4.1 that shows a client making an Access Token 597 Request using an assertion as an Authorization Grant. 599 6.3.1. Client Acting on Behalf of an Anonymous User 601 When a client is accessing resources on behalf of an anonymous user, 602 the Subject indicates to the Authorization Server that the client is 603 acting on-behalf of an anonymous user as defined by the Authorization 604 Server. It is implied that authorization is based upon additional 605 criteria, such as additional attributes or claims provided in the 606 assertion. For example, a client may present an assertion from a 607 trusted issuer asserting that the bearer is over 18 via an included 608 claim. In this case, no additional information about the user's 609 identity is included, yet all the data needed to issue an access 610 token is present. 612 7. Interoperability Considerations 614 This specification defines a framework for using assertions with 615 OAuth 2.0. However, as an abstract framework in which the data 616 formats used for representing many values are not defined, on its 617 own, this specification is not sufficient to produce interoperable 618 implementations. 620 Two other specifications that profile this framework for specific 621 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 622 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 623 uses JSON Web Tokens (JWTs). These two instantiations of this 624 framework specify additional details about the assertion encoding and 625 processing rules for using those kinds of assertions with OAuth 2.0. 627 However, even when profiled for specific assertion types, agreements 628 between system entities regarding identifiers, keys, and endpoints 629 are required in order to achieve interoperable deployments. Specific 630 items that require agreement are as follows: values for the issuer 631 and audience identifiers, supported assertion and client 632 authentication types, the location of the token endpoint, the key 633 used to apply and verify the digital signature or keyed message 634 digest over the assertion, one-time use restrictions on assertions, 635 maximum assertion lifetime allowed, and the specific subject and 636 attribute requirements of the assertion. The exchange of such 637 information is explicitly out of scope for this specification. 638 Deployments for particular trust frameworks, circles of trust, or 639 other uses cases will need to agree among the participants on the 640 kinds of values to be used for some abstract fields defined by this 641 specification. In some cases, additional profiles may be created 642 that constrain or prescribe these values or specify how they are to 643 be exchanged. The OAuth 2.0 Dynamic Client Registration Protocol 644 [I-D.ietf-oauth-dyn-reg] is one such profile that enables OAuth 645 Clients to register metadata about themselves at an Authorization 646 Server. 648 8. Security Considerations 650 This section discusses security considerations that apply when using 651 assertions with OAuth 2.0 as described in this document. As 652 discussed in Section 3, there are two different ways to obtain 653 assertions: either as self-issued or obtained from a third party 654 token service. While the actual interactions for obtaining an 655 assertion are outside the scope of this document, the details are 656 important from a security perspective. Section 3 discusses the high 657 level architectural aspects. Many of the security considerations 658 discussed in this section are applicable to both the OAuth exchange 659 as well as the client obtaining the assertion. 661 The remainder of this section focuses on the exchanges that concern 662 presenting an assertion for client authentication and for the 663 authorization grant. 665 8.1. Forged Assertion 667 Threat: 668 An adversary could forge or alter an assertion in order to obtain 669 an access token (in case of the authorization grant) or to 670 impersonate a client (in case of the client authentication 671 mechanism). 673 Countermeasures: 674 To avoid this kind of attack, the entities must assure that proper 675 mechanisms for protecting the integrity of the assertion are 676 employed. This includes the issuer digitally signing the 677 assertion or computing a keyed message digest over the assertion. 679 8.2. Stolen Assertion 681 Threat: 682 An adversary may be able obtain an assertion (e.g., by 683 eavesdropping) and then reuse it (replay it) at a later point in 684 time. 686 Countermeasures: 687 The primary mitigation for this threat is the use of secure 688 communication channels with server authentication for all network 689 exchanges. 691 An assertion may also contain several elements to prevent replay 692 attacks. There is, however, a clear tradeoff between reusing an 693 assertion for multiple exchanges and obtaining and creating new 694 fresh assertions. 696 Authorization Servers and Resource Servers may use a combination 697 of the Assertion ID and Issued At/Expires At attributes for replay 698 protection. Previously processed assertions may be rejected based 699 on the Assertion ID. The addition of the validity window relieves 700 the authorization server from maintaining an infinite state table 701 of processed Assertion IDs. 703 8.3. Unauthorized Disclosure of Personal Information 705 Threat: 707 The ability for other entities to obtain information about an 708 individual, such as authentication information, role in an 709 organization, or other authorization relevant information, raises 710 privacy concerns. 712 Countermeasures: 713 To address the threats, two cases need to be differentiated: 715 First, a third party that did not participate in any of the 716 exchange is prevented from eavesdropping on the content of the 717 assertion by employing confidentiality protection of the exchange 718 using TLS. This ensures that an eavesdropper on the wire is 719 unable to obtain information. However, this does not prevent 720 legitimate protocol entities from obtaining information that they 721 are not allowed to possess from assertions. Some assertion 722 formats allow for the assertion to be encrypted, preventing 723 unauthorized parties from inspecting the content. 725 Second, an Authorization Server may obtain an assertion that was 726 created by a third party token service and that token service may 727 have placed attributes into the assertion. To mitigate potential 728 privacy problems, prior consent for the release of such attribute 729 information from the resource owner should be obtained. OAuth 730 itself does not directly provide such capabilities, but this 731 consent approval may be obtained using other identity management 732 protocols, user consent interactions, or in an out-of-band 733 fashion. 735 For the cases where a third party token service creates assertions 736 to be used for client authentication, privacy concerns are 737 typically lower, since many of these clients are Web servers 738 rather than individual devices operated by humans. If the 739 assertions are used for client authentication of devices or 740 software that can be closely linked to end users, then privacy 741 protection safeguards need to be taken into consideration. 743 Further guidance on privacy friendly protocol design can be found 744 in [I-D.iab-privacy-considerations]. 746 9. IANA Considerations 748 This is a request to add three values, as listed in the sub-sections 749 below, to the "OAuth Parameters" registry established by RFC 6749 750 [RFC6749]. 752 9.1. assertion Parameter Registration 753 o Parameter name: assertion 755 o Parameter usage location: token request 757 o Change controller: IETF 759 o Specification document(s): [[this document]] 761 9.2. client_assertion Parameter Registration 763 o Parameter name: client_assertion 765 o Parameter usage location: token request 767 o Change controller: IETF 769 o Specification document(s): [[this document]] 771 9.3. client_assertion_type Parameter Registration 773 o Parameter name: client_assertion_type 775 o Parameter usage location: token request 777 o Change controller: IETF 779 o Specification document(s): [[this document]] 781 10. References 783 10.1. Normative References 785 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 786 Requirement Levels", BCP 14, RFC 2119, March 1997. 788 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 789 Resource Identifier (URI): Generic Syntax", STD 66, RFC 790 3986, January 2005. 792 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 793 6749, October 2012. 795 10.2. Informative References 797 [I-D.iab-privacy-considerations] 798 Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 799 Morris, J., Hansen, M., and R. Smith, "Privacy 800 Considerations for Internet Protocols", draft-iab-privacy- 801 considerations-09 (work in progress), May 2013. 803 [I-D.ietf-oauth-dyn-reg] 804 Richer, J., Bradley, J., Jones, M., and M. Machulak, 805 "OAuth 2.0 Dynamic Client Registration Protocol", draft- 806 ietf-oauth-dyn-reg-13 (work in progress), July 2013. 808 [I-D.ietf-oauth-jwt-bearer] 809 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 810 (JWT) Profile for OAuth 2.0 Client Authentication and 811 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 812 in progress), December 2013. 814 [I-D.ietf-oauth-saml2-bearer] 815 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 816 Profile for OAuth 2.0 Client Authentication and 817 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 818 in progress), December 2013. 820 [OASIS.WS-Trust] 821 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 822 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", Feb 823 2009. 825 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 826 for OAuth", RFC 6755, October 2012. 828 Appendix A. Acknowledgements 830 The authors wish to thank the following people that have influenced 831 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 832 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 833 specification, and the members of the OAuth working group. 835 Appendix B. Document History 837 [[ to be removed by the RFC editor before publication as an RFC ]] 839 draft-ietf-oauth-assertions-13 841 o Clean up language around subject per the subject part of http:// 842 www.ietf.org/mail-archive/web/oauth/current/msg12155.html 844 o Replace "Client Credentials flow" by "Client Credentials _Grant_" 845 as suggested in http://www.ietf.org/mail-archive/web/oauth/current 846 /msg12155.html 848 o For consistency with SAML and JWT per http://www.ietf.org/mail- 849 archive/web/oauth/current/msg12251.html and http://www.ietf.org/ 850 mail-archive/web/oauth/current/msg12253.html Stated that "In the 851 absence of an application profile specifying otherwise, compliant 852 applications MUST compare the audience values using the Simple 853 String Comparison method defined in Section 6.2.1 of RFC 3986." 855 o Added one-time use, maximum lifetime, and specific subject and 856 attribute requirements to Interoperability Considerations. 858 draft-ietf-oauth-assertions-12 860 o Stated that issuer and audience values SHOULD be compared using 861 the Simple String Comparison method defined in Section 6.2.1 of 862 RFC 3986 unless otherwise specified by the application. 864 draft-ietf-oauth-assertions-11 866 o Addressed comments from IESG evaluation https:// 867 datatracker.ietf.org/doc/draft-ietf-oauth-assertions/ballot/. 869 o Reworded Interoperability Considerations to state what 870 identifiers, keys, endpoints, etc. need to be exchanged/agreed 871 upon. 873 o Added brief description of assertion to the into and included a 874 reference to Section 3 (Framework) where it's described more. 876 o Changed such that a self-issued assertion must (was should) have 877 the client id as the issuer. 879 o Changed "Specific Assertion Format and Processing Rules" to 880 "Common Scenarios" and reworded to be more suggestive of common 881 practices, rather than trying to be normative. Also removed lots 882 of repetitive text in that section. 884 o Refined language around audience, subject, client identifiers, 885 etc. to hopefully be clearer and less redundant. 887 o Changed title from "Assertion Framework for OAuth 2.0" to 888 "Assertion Framework for OAuth 2.0 Client Authentication and 889 Authorization Grants" to be more explicit about the scope of the 890 document per http://www.ietf.org/mail-archive/web/oauth/current/ 891 msg11063.html. 893 o Noted that authentication of the client per Section 3.2.1 of OAuth 894 is optional for an access token request with an assertion as an 895 authorization grant and removed client_id from the associated 896 example. 898 draft-ietf-oauth-assertions-10 900 o Changed term "Principal" to "Subject". 902 o Added Interoperability Considerations section. 904 o Applied Shawn Emery's comments from the security directorate 905 review, including correcting urn:ietf:params:oauth:grant_type:* to 906 urn:ietf:params:oauth:grant-type:*. 908 draft-ietf-oauth-assertions-09 910 o Allow audience values to not be URIs. 912 o Added informative references to draft-ietf-oauth-saml2-bearer and 913 draft-ietf-oauth-jwt-bearer. 915 o Clarified that the statements about possible issuers are non- 916 normative by using the language "Examples of issuers". 918 draft-ietf-oauth-assertions-08 920 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 922 o Tidy up IANA consideration section 924 draft-ietf-oauth-assertions-07 926 o Reference RFC 6749. 928 o Remove extraneous word per http://www.ietf.org/mail-archive/web/ 929 oauth/current/msg10029.html 931 draft-ietf-oauth-assertions-06 933 o Add more text to intro explaining that an assertion grant type can 934 be used with or without client authentication/identification and 935 that client assertion authentication is nothing more than an 936 alternative way for a client to authenticate to the token endpoint 938 draft-ietf-oauth-assertions-05 940 o Non-normative editorial cleanups 941 o Updated document to incorporate the review comments from the 942 shepherd - thread and alternative draft at http://www.ietf.org/ 943 mail-archive/web/oauth/current/msg09437.html 945 o Added reference to draft-ietf-oauth-urn-sub-ns and include 946 suggestions on urn:ietf:params:oauth:[grant-type|client-assertion- 947 type]:* URNs 949 draft-ietf-oauth-assertions-03 951 o updated reference to draft-ietf-oauth-v2 from -25 to -26 953 draft-ietf-oauth-assertions-02 955 o Added text about limited lifetime ATs and RTs per http:// 956 www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 958 o Changed the line breaks in some examples to avoid awkward 959 rendering to text format. Also removed encoded '=' padding from a 960 few examples because both known derivative specs, SAML and JWT, 961 omit the padding char in serialization/encoding. 963 o Remove section 7 on error responses and move that (somewhat 964 modified) content into subsections of section 4 broken up by authn 965 /authz per http://www.ietf.org/mail-archive/web/oauth/current/ 966 msg08735.html. 968 o Rework the text about "MUST validate ... in order to establish a 969 mapping between ..." per http://www.ietf.org/mail-archive/web/ 970 oauth/current/msg08872.html and http://www.ietf.org/mail-archive/ 971 web/oauth/current/msg08749.html. 973 o Change "The Principal MUST identify an authorized accessor. If 974 the assertion is self-issued, the Principal SHOULD be the 975 client_id" in 6.1 per http://www.ietf.org/mail-archive/web/oauth/ 976 current/msg08873.html. 978 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 979 oauth-v2 (rather than self) http://www.ietf.org/mail-archive/web/ 980 oauth/current/msg08874.html. 982 o Move the "Section 3 of" out of the xref to hopefully fix the link 983 in 4.1 and remove the client_id bullet from 4.2 per http:// 984 www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 986 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 987 some then redundant text per http://www.ietf.org/mail-archive/web/ 988 oauth/current/msg08890.html. 990 o Change "The following format and processing rules SHOULD be 991 applied" to "The following format and processing rules apply" in 992 sections 6.x to remove conflicting normative qualification of 993 other normative statements per http://www.ietf.org/mail-archive/ 994 web/oauth/current/msg08892.html. 996 o Add text the client_id must id the client to 4.1 and remove 997 similar text from other places per http://www.ietf.org/mail- 998 archive/web/oauth/current/msg08893.html. 1000 o Remove the MUST from the text prior to the HTTP parameter 1001 definitions per http://www.ietf.org/mail-archive/web/oauth/current 1002 /msg08920.html. 1004 o Updated examples to use grant_type and client_assertion_type 1005 values from the OAuth SAML Assertion Profiles spec. 1007 Authors' Addresses 1009 Brian Campbell 1010 Ping Identity 1012 Email: brian.d.campbell@gmail.com 1014 Chuck Mortimore 1015 Salesforce.com 1017 Email: cmortimore@salesforce.com 1019 Michael B. Jones 1020 Microsoft 1022 Email: mbj@microsoft.com 1024 Yaron Y. Goland 1025 Microsoft 1027 Email: yarong@microsoft.com