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