idnits 2.17.1 draft-ietf-oauth-assertions-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 19, 2014) is 3690 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-16 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: September 20, 2014 Salesforce 6 M. Jones 7 Y. Goland 8 Microsoft 9 March 19, 2014 11 Assertion Framework for OAuth 2.0 Client Authentication and 12 Authorization Grants 13 draft-ietf-oauth-assertions-15 15 Abstract 17 This specification provides a framework for the use of assertions 18 with OAuth 2.0 in the form of a new client authentication mechanism 19 and a new authorization grant type. Mechanisms are specified for 20 transporting assertions during interactions with a token endpoint, as 21 well as general processing rules. 23 The intent of this specification is to provide a common framework for 24 OAuth 2.0 to interwork with other identity systems using assertions, 25 and to provide alternative client authentication mechanisms. 27 Note that this specification only defines abstract message flows and 28 processing rules. In order to be implementable, companion 29 specifications are necessary to provide the corresponding concrete 30 instantiations. 32 Status of this Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on September 20, 2014. 49 Copyright Notice 51 Copyright (c) 2014 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. Notational Conventions . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . 15 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 84 8.1. Forged Assertion . . . . . . . . . . . . . . . . . . . . . 16 85 8.2. Stolen Assertion . . . . . . . . . . . . . . . . . . . . . 16 86 8.3. Unauthorized Disclosure of Personal Information . . . . . 17 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 88 9.1. assertion Parameter Registration . . . . . . . . . . . . . 18 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 . . . . . . . . . . . . . . . . . . 19 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. Notational Conventions 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 303 REQUIRED. The format of the assertion as defined by the 304 authorization server. The value MUST be an absolute URI. 306 assertion 307 REQUIRED. The assertion being used as an authorization grant. 308 Specific serialization of the assertion is defined by profile 309 documents. The serialization MUST be encoded for transport within 310 HTTP forms. It is RECOMMENDED that base64url be used. 312 scope 313 OPTIONAL. The requested scope as described in Section 3.3 of 314 OAuth 2.0 [RFC6749]. When exchanging assertions for access 315 tokens, the authorization for the token has been previously 316 granted through some out-of-band mechanism. As such, the 317 requested scope MUST be equal or lesser than the scope originally 318 granted to the authorized accessor. If the scope parameter and/or 319 value are omitted, the scope MUST be treated as equal to the scope 320 originally granted to the authorized accessor. The Authorization 321 Server MUST limit the scope of the issued access token to be equal 322 or lesser than the scope originally granted to the authorized 323 accessor. 325 Authentication of the client is optional, as described in Section 326 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the "client_id" is 327 only needed when a form of client authentication that relies on the 328 parameter is used. 330 The following non-normative example demonstrates an assertion being 331 used as an authorization grant (with extra line breaks for display 332 purposes only): 334 POST /token HTTP/1.1 335 Host: server.example.com 336 Content-Type: application/x-www-form-urlencoded 338 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer& 339 assertion=PHNhbWxwOl...[omitted for brevity]...ZT4 341 An assertion used in this context is generally a short lived 342 representation of the authorization grant and authorization servers 343 SHOULD NOT issue access tokens with a lifetime that exceeds the 344 validity period of the assertion by a significant period. In 345 practice, that will usually mean that refresh tokens are not issued 346 in response to assertion grant requests and access tokens will be 347 issued with a reasonably short lifetime. Clients can refresh an 348 expired access token by requesting a new one using the same 349 assertion, if it is still valid, or with a new assertion. 351 An IETF URN for use as the "grant_type" value can be requested using 352 the template in [RFC6755]. A URN of the form 353 urn:ietf:params:oauth:grant-type:* is suggested. 355 4.1.1. Error Responses 357 If an assertion is not valid or has expired, the Authorization Server 358 MUST construct an error response as defined in OAuth 2.0 [RFC6749]. 359 The value of the "error" parameter MUST be the "invalid_grant" error 360 code. The authorization server MAY include additional information 361 regarding the reasons the assertion was considered invalid using the 362 "error_description" or "error_uri" parameters. 364 For example: 366 HTTP/1.1 400 Bad Request 367 Content-Type: application/json 368 Cache-Control: no-store 370 { 371 "error":"invalid_grant", 372 "error_description":"Audience validation failed" 373 } 375 4.2. Using Assertions for Client Authentication 377 The following section defines the use of assertions as client 378 credentials as an extension of Section 2.3 of OAuth 2.0 [RFC6749]. 379 When using assertions as client credentials, the client includes the 380 assertion and related information using the following HTTP request 381 parameters: 383 client_assertion_type 384 REQUIRED. The format of the assertion as defined by the 385 authorization server. The value MUST be an absolute URI. 387 client_assertion 388 REQUIRED. The assertion being used to authenticate the client. 389 Specific serialization of the assertion is defined by profile 390 documents. The serialization MUST be encoded for transport within 391 HTTP forms. It is RECOMMENDED that base64url be used. 393 client_id 394 OPTIONAL. The client identifier as described in Section 2.2 of 395 OAuth 2.0 [RFC6749]. The "client_id" is unnecessary for client 396 assertion authentication because the client is identified by the 397 subject of the assertion. If present, the value of the 398 "client_id" parameter MUST identify the same client as is 399 identified by the client assertion. 401 The following non-normative example demonstrates a client 402 authenticating using an assertion during an Access Token Request, as 403 defined in Section 4.1.3 of OAuth 2.0 [RFC6749] (with extra line 404 breaks for display purposes only): 406 POST /token HTTP/1.1 407 Host: server.example.com 408 Content-Type: application/x-www-form-urlencoded 410 grant_type=authorization_code& 411 code=i1WsRn1uB1& 412 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 413 %3Aclient-assertion-type%3Asaml2-bearer& 414 client_assertion=PHNhbW...[omitted for brevity]...ZT 416 Token endpoints can differentiate between assertion based credentials 417 and other client credential types by looking for the presence of the 418 "client_assertion" and "client_assertion_type" parameters, which will 419 only be present when using assertions for client authentication. 421 An IETF URN for use as the "client_assertion_type" value may be 422 requested using the template in [RFC6755]. A URN of the form 423 urn:ietf:params:oauth:client-assertion-type:* is suggested. 425 4.2.1. Error Responses 427 If an assertion is invalid for any reason or if more than one client 428 authentication mechanism is used, the Authorization Server MUST 429 construct an error response as defined in OAuth 2.0 [RFC6749]. The 430 value of the "error" parameter MUST be the "invalid_client" error 431 code. The authorization server MAY include additional information 432 regarding the reasons the client assertion was considered invalid 433 using the "error_description" or "error_uri" parameters. 435 For example: 437 HTTP/1.1 400 Bad Request 438 Content-Type: application/json 439 Cache-Control: no-store 441 { 442 "error":"invalid_client" 443 "error_description":"assertion has expired" 444 } 446 5. Assertion Content and Processing 448 This section provides a general content and processing model for the 449 use of assertions in OAuth 2.0 [RFC6749]. 451 5.1. Assertion Metamodel 453 The following are entities and metadata involved in the issuance, 454 exchange, and processing of assertions in OAuth 2.0. These are 455 general terms, abstract from any particular assertion format. 456 Mappings of these terms into specific representations are provided by 457 profiles of this specification. 459 Issuer 460 A unique identifier for the entity that issued the assertion. 461 Generally this is the entity that holds the key material used to 462 sign or integrity protect the assertion. Examples of issuers are 463 OAuth clients (when assertions are self-issued) and third party 464 security token services. If the assertion is self-issued, the 465 Issuer value is the client identifier. If the assertion was 466 issued by a Security Token Service (STS), the Issuer should 467 identify the STS in a manner recognized by the Authorization 468 Server. In the absence of an application profile specifying 469 otherwise, compliant applications MUST compare Issuer values using 470 the Simple String Comparison method defined in Section 6.2.1 of 471 RFC 3986 [RFC3986]. 473 Subject 474 A unique identifier for the principal that is the subject of the 475 assertion. 477 * When using assertions for client authentication, the Subject 478 identifies the client to the authorization server using the 479 value of the "client_id" of the OAuth client. 481 * When using assertions as an authorization grant, the Subject 482 identifies an authorized accessor for which the access token is 483 being requested (typically the resource owner, or an authorized 484 delegate). 486 Audience 487 A value that identifies the party or parties intended to process 488 the assertion. The URL of the Token Endpoint, as defined in 489 Section 3.2 of OAuth 2.0 [RFC6749], can be used to indicate that 490 the authorization server as a valid intended audience of the 491 assertion. In the absence of an application profile specifying 492 otherwise, compliant applications MUST compare the audience values 493 using the Simple String Comparison method defined in Section 6.2.1 494 of RFC 3986 [RFC3986]. 496 Issued At 497 The time at which the assertion was issued. While the 498 serialization may differ by assertion format, it is REQUIRED that 499 the time be expressed in UTC with no time zone component. 501 Expires At 502 The time at which the assertion expires. While the serialization 503 may differ by assertion format, it is REQUIRED that the time be 504 expressed in UTC with no time zone component. 506 Assertion ID 507 A nonce or unique identifier for the assertion. The Assertion ID 508 may be used by implementations requiring message de-duplication 509 for one-time use assertions. Any entity that assigns an 510 identifier MUST ensure that there is negligible probability that 511 that entity or any other entity will accidentally assign the same 512 identifier to a different data object. 514 5.2. General Assertion Format and Processing Rules 516 The following are general format and processing rules for the use of 517 assertions in OAuth: 519 o The assertion MUST contain an Issuer. The Issuer MUST identify 520 the entity that issued the assertion as recognized by the 521 Authorization Server. If an assertion is self-issued, the Issuer 522 MUST be the value of the client's "client_id". 524 o The assertion MUST contain a Subject. The Subject identifies an 525 authorized accessor for which the access token is being requested 526 (typically the resource owner, or an authorized delegate). When 527 the client is acting on behalf of itself, the Subject MUST be the 528 value of the client's "client_id". 530 o The assertion MUST contain an Audience that identifies the 531 Authorization Server as the intended audience. Assertions that do 532 not identify the Authorization Server as an intended audience MUST 533 be rejected. 535 o The assertion MUST contain an Expires At entity that limits the 536 time window during which the assertion can be used. The 537 authorization server MUST reject assertions that have expired 538 (subject to allowable clock skew between systems). The 539 authorization server MAY reject assertions with an Expires At 540 attribute value that is unreasonably far in the future. 542 o The assertion MAY contain an Issued At entity containing the UTC 543 time at which the assertion was issued. 545 o The Authorization Server MUST reject assertions with an invalid 546 signature or keyed message digest. The algorithm used to validate 547 the signature or message authentication code and the mechanism for 548 designating the secret used to generate the signature or message 549 authentication code over the assertion are beyond the scope of 550 this specification. 552 6. Common Scenarios 554 The following provides additional guidance, beyond the format and 555 processing rules defined in Section 4 and Section 5, on assertion use 556 for a number of common use cases. 558 6.1. Client Authentication 560 A client uses an assertion to authenticate to the authorization 561 server's token endpoint by using the "client_assertion_type" and 562 "client_assertion" parameters as defined in Section 4.2. The Subject 563 of the assertion identifies the client. If the assertion is self- 564 issued by the client, the Issuer of the assertion also identifies the 565 client. 567 The example in Section 4.2 that shows a client authenticating using 568 an assertion during an Access Token Request. 570 6.2. Client Acting on Behalf of Itself 572 When a client is accessing resources on behalf of itself, it does so 573 in a manner analogous to the Client Credentials Grant defined in 574 Section 4.4 of OAuth 2.0 [RFC6749]. This is a special case that 575 combines both the authentication and authorization grant usage 576 patterns. In this case, the interactions with the authorization 577 server should be treated as using an assertion for Client 578 Authentication according to Section 4.2, while using the grant_type 579 parameter with the value "client_credentials" to indicate that the 580 client is requesting an access token using only its client 581 credentials. 583 The following non-normative example demonstrates an assertion being 584 used for a Client Credentials Access Token Request, as defined in 585 Section 4.4.2 of OAuth 2.0 [RFC6749] (with extra line breaks for 586 display purposes only): 588 POST /token HTTP/1.1 589 Host: server.example.com 590 Content-Type: application/x-www-form-urlencoded 592 grant_type=client_credentials& 593 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth 594 %3Aclient-assertion-type%3Asaml2-bearer& 595 client_assertion=PHNhbW...[omitted for brevity]...ZT 597 6.3. Client Acting on Behalf of a User 599 When a client is accessing resources on behalf of a user, it does so 600 by using the "grant_type" and "assertion" parameters as defined in 601 Section 4.1. The Subject identifies an authorized accessor for which 602 the access token is being requested (typically the resource owner, or 603 an authorized delegate). 605 The example in Section 4.1 that shows a client making an Access Token 606 Request using an assertion as an Authorization Grant. 608 6.3.1. Client Acting on Behalf of an Anonymous User 610 When a client is accessing resources on behalf of an anonymous user, 611 the Subject indicates to the Authorization Server that the client is 612 acting on-behalf of an anonymous user as defined by the Authorization 613 Server. It is implied that authorization is based upon additional 614 criteria, such as additional attributes or claims provided in the 615 assertion. For example, a client may present an assertion from a 616 trusted issuer asserting that the bearer is over 18 via an included 617 claim. In this case, no additional information about the user's 618 identity is included, yet all the data needed to issue an access 619 token is present. 621 7. Interoperability Considerations 623 This specification defines a framework for using assertions with 624 OAuth 2.0. However, as an abstract framework in which the data 625 formats used for representing many values are not defined, on its 626 own, this specification is not sufficient to produce interoperable 627 implementations. 629 Two other specifications that profile this framework for specific 630 assertion have been developed: one [I-D.ietf-oauth-saml2-bearer] uses 631 SAML 2.0-based assertions and the other [I-D.ietf-oauth-jwt-bearer] 632 uses JSON Web Tokens (JWTs). These two instantiations of this 633 framework specify additional details about the assertion encoding and 634 processing rules for using those kinds of assertions with OAuth 2.0. 636 However, even when profiled for specific assertion types, agreements 637 between system entities regarding identifiers, keys, and endpoints 638 are required in order to achieve interoperable deployments. Specific 639 items that require agreement are as follows: values for the issuer 640 and audience identifiers, supported assertion and client 641 authentication types, the location of the token endpoint, the key 642 used to apply and verify the digital signature or keyed message 643 digest over the assertion, one-time use restrictions on assertions, 644 maximum assertion lifetime allowed, and the specific subject and 645 attribute requirements of the assertion. The exchange of such 646 information is explicitly out of scope for this specification. 647 Deployments for particular trust frameworks, circles of trust, or 648 other uses cases will need to agree among the participants on the 649 kinds of values to be used for some abstract fields defined by this 650 specification. In some cases, additional profiles may be created 651 that constrain or prescribe these values or specify how they are to 652 be exchanged. The OAuth 2.0 Dynamic Client Registration Core 653 Protocol [I-D.ietf-oauth-dyn-reg] is one such profile that enables 654 OAuth Clients to register metadata about themselves at an 655 Authorization Server. 657 8. Security Considerations 659 This section discusses security considerations that apply when using 660 assertions with OAuth 2.0 as described in this document. As 661 discussed in Section 3, there are two different ways to obtain 662 assertions: either as self-issued or obtained from a third party 663 token service. While the actual interactions for obtaining an 664 assertion are outside the scope of this document, the details are 665 important from a security perspective. Section 3 discusses the high 666 level architectural aspects. Many of the security considerations 667 discussed in this section are applicable to both the OAuth exchange 668 as well as the client obtaining the assertion. 670 The remainder of this section focuses on the exchanges that concern 671 presenting an assertion for client authentication and for the 672 authorization grant. 674 8.1. Forged Assertion 676 Threat: 677 An adversary could forge or alter an assertion in order to obtain 678 an access token (in case of the authorization grant) or to 679 impersonate a client (in case of the client authentication 680 mechanism). 682 Countermeasures: 683 To avoid this kind of attack, the entities must assure that proper 684 mechanisms for protecting the integrity of the assertion are 685 employed. This includes the issuer digitally signing the 686 assertion or computing a keyed message digest over the assertion. 688 8.2. Stolen Assertion 690 Threat: 691 An adversary may be able obtain an assertion (e.g., by 692 eavesdropping) and then reuse it (replay it) at a later point in 693 time. 695 Countermeasures: 696 The primary mitigation for this threat is the use of secure 697 communication channels with server authentication for all network 698 exchanges. 700 An assertion may also contain several elements to prevent replay 701 attacks. There is, however, a clear tradeoff between reusing an 702 assertion for multiple exchanges and obtaining and creating new 703 fresh assertions. 705 Authorization Servers and Resource Servers may use a combination 706 of the Assertion ID and Issued At/Expires At attributes for replay 707 protection. Previously processed assertions may be rejected based 708 on the Assertion ID. The addition of the validity window relieves 709 the authorization server from maintaining an infinite state table 710 of processed Assertion IDs. 712 8.3. Unauthorized Disclosure of Personal Information 714 Threat: 715 The ability for other entities to obtain information about an 716 individual, such as authentication information, role in an 717 organization, or other authorization relevant information, raises 718 privacy concerns. 720 Countermeasures: 721 To address the threats, two cases need to be differentiated: 723 First, a third party that did not participate in any of the 724 exchange is prevented from eavesdropping on the content of the 725 assertion by employing confidentiality protection of the exchange 726 using TLS. This ensures that an eavesdropper on the wire is 727 unable to obtain information. However, this does not prevent 728 legitimate protocol entities from obtaining information that they 729 are not allowed to possess from assertions. Some assertion 730 formats allow for the assertion to be encrypted, preventing 731 unauthorized parties from inspecting the content. 733 Second, an Authorization Server may obtain an assertion that was 734 created by a third party token service and that token service may 735 have placed attributes into the assertion. To mitigate potential 736 privacy problems, prior consent for the release of such attribute 737 information from the resource owner should be obtained. OAuth 738 itself does not directly provide such capabilities, but this 739 consent approval may be obtained using other identity management 740 protocols, user consent interactions, or in an out-of-band 741 fashion. 743 For the cases where a third party token service creates assertions 744 to be used for client authentication, privacy concerns are 745 typically lower, since many of these clients are Web servers 746 rather than individual devices operated by humans. If the 747 assertions are used for client authentication of devices or 748 software that can be closely linked to end users, then privacy 749 protection safeguards need to be taken into consideration. 751 Further guidance on privacy friendly protocol design can be found 752 in [RFC6973]. 754 9. IANA Considerations 756 This is a request to add three values, as listed in the sub-sections 757 below, to the "OAuth Parameters" registry established by RFC 6749 758 [RFC6749]. 760 9.1. assertion Parameter Registration 762 o Parameter name: assertion 764 o Parameter usage location: token request 766 o Change controller: IETF 768 o Specification document(s): [[this document]] 770 9.2. client_assertion Parameter Registration 772 o Parameter name: client_assertion 774 o Parameter usage location: token request 776 o Change controller: IETF 778 o Specification document(s): [[this document]] 780 9.3. client_assertion_type Parameter Registration 782 o Parameter name: client_assertion_type 784 o Parameter usage location: token request 786 o Change controller: IETF 788 o Specification document(s): [[this document]] 790 10. References 792 10.1. Normative References 794 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 795 Requirement Levels", BCP 14, RFC 2119, March 1997. 797 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 798 Resource Identifier (URI): Generic Syntax", STD 66, 799 RFC 3986, January 2005. 801 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 802 RFC 6749, October 2012. 804 10.2. Informative References 806 [I-D.ietf-oauth-dyn-reg] 807 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 808 Hunt, "OAuth 2.0 Dynamic Client Registration Core 809 Protocol", draft-ietf-oauth-dyn-reg-16 (work in progress), 810 February 2014. 812 [I-D.ietf-oauth-jwt-bearer] 813 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 814 (JWT) Profile for OAuth 2.0 Client Authentication and 815 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 816 in progress), March 2014. 818 [I-D.ietf-oauth-saml2-bearer] 819 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 820 Profile for OAuth 2.0 Client Authentication and 821 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 822 in progress), March 2014. 824 [OASIS.WS-Trust] 825 Nadalin, A., Ed., Goodner, M., Ed., Gudgin, M., Ed., 826 Barbir, A., Ed., and H. Granqvist, Ed., "WS-Trust", 827 Feb 2009. 829 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 830 for OAuth", RFC 6755, October 2012. 832 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 833 Morris, J., Hansen, M., and R. Smith, "Privacy 834 Considerations for Internet Protocols", RFC 6973, 835 July 2013. 837 Appendix A. Acknowledgements 839 The authors wish to thank the following people that have influenced 840 or contributed this specification: Paul Madsen, Eric Sachs, Jian Cai, 841 Tony Nadalin, Hannes Tschofenig, the authors of the OAuth WRAP 842 specification, and the members of the OAuth working group. 844 Appendix B. Document History 846 [[ to be removed by the RFC editor before publication as an RFC ]] 847 o Updated references. 849 o Improved formatting of hanging lists. 851 draft-ietf-oauth-assertions-14 853 o Update reference: draft-iab-privacy-considerations is now RFC 6973 855 o Update reference: draft-ietf-oauth-dyn-reg from -13 to -15 857 draft-ietf-oauth-assertions-13 859 o Clean up language around subject per the subject part of 860 http://www.ietf.org/mail-archive/web/oauth/current/msg12155.html 862 o Replace "Client Credentials flow" by "Client Credentials _Grant_" 863 as suggested in 864 http://www.ietf.org/mail-archive/web/oauth/current/msg12155.html 866 o For consistency with SAML and JWT per 867 http://www.ietf.org/mail-archive/web/oauth/current/msg12251.html 868 and 869 http://www.ietf.org/mail-archive/web/oauth/current/msg12253.html 870 Stated that "In the absence of an application profile specifying 871 otherwise, compliant applications MUST compare the audience values 872 using the Simple String Comparison method defined in Section 6.2.1 873 of RFC 3986." 875 o Added one-time use, maximum lifetime, and specific subject and 876 attribute requirements to Interoperability Considerations. 878 draft-ietf-oauth-assertions-12 880 o Stated that issuer and audience values SHOULD be compared using 881 the Simple String Comparison method defined in Section 6.2.1 of 882 RFC 3986 unless otherwise specified by the application. 884 draft-ietf-oauth-assertions-11 886 o Addressed comments from IESG evaluation https:// 887 datatracker.ietf.org/doc/draft-ietf-oauth-assertions/ballot/. 889 o Reworded Interoperability Considerations to state what 890 identifiers, keys, endpoints, etc. need to be exchanged/agreed 891 upon. 893 o Added brief description of assertion to the into and included a 894 reference to Section 3 (Framework) where it's described more. 896 o Changed such that a self-issued assertion must (was should) have 897 the client id as the issuer. 899 o Changed "Specific Assertion Format and Processing Rules" to 900 "Common Scenarios" and reworded to be more suggestive of common 901 practices, rather than trying to be normative. Also removed lots 902 of repetitive text in that section. 904 o Refined language around audience, subject, client identifiers, 905 etc. to hopefully be clearer and less redundant. 907 o Changed title from "Assertion Framework for OAuth 2.0" to 908 "Assertion Framework for OAuth 2.0 Client Authentication and 909 Authorization Grants" to be more explicit about the scope of the 910 document per 911 http://www.ietf.org/mail-archive/web/oauth/current/msg11063.html. 913 o Noted that authentication of the client per Section 3.2.1 of OAuth 914 is optional for an access token request with an assertion as an 915 authorization grant and removed client_id from the associated 916 example. 918 draft-ietf-oauth-assertions-10 920 o Changed term "Principal" to "Subject". 922 o Added Interoperability Considerations section. 924 o Applied Shawn Emery's comments from the security directorate 925 review, including correcting urn:ietf:params:oauth:grant_type:* to 926 urn:ietf:params:oauth:grant-type:*. 928 draft-ietf-oauth-assertions-09 930 o Allow audience values to not be URIs. 932 o Added informative references to draft-ietf-oauth-saml2-bearer and 933 draft-ietf-oauth-jwt-bearer. 935 o Clarified that the statements about possible issuers are non- 936 normative by using the language "Examples of issuers". 938 draft-ietf-oauth-assertions-08 939 o Update reference to RFC 6755 from draft-ietf-oauth-urn-sub-ns 941 o Tidy up IANA consideration section 943 draft-ietf-oauth-assertions-07 945 o Reference RFC 6749. 947 o Remove extraneous word per 948 http://www.ietf.org/mail-archive/web/oauth/current/msg10029.html 950 draft-ietf-oauth-assertions-06 952 o Add more text to intro explaining that an assertion grant type can 953 be used with or without client authentication/identification and 954 that client assertion authentication is nothing more than an 955 alternative way for a client to authenticate to the token endpoint 957 draft-ietf-oauth-assertions-05 959 o Non-normative editorial cleanups 961 draft-ietf-oauth-assertions-04 963 o Updated document to incorporate the review comments from the 964 shepherd - thread and alternative draft at 965 http://www.ietf.org/mail-archive/web/oauth/current/msg09437.html 967 o Added reference to draft-ietf-oauth-urn-sub-ns and include 968 suggestions on 969 urn:ietf:params:oauth:[grant-type|client-assertion-type]:* URNs 971 draft-ietf-oauth-assertions-03 973 o updated reference to draft-ietf-oauth-v2 from -25 to -26 975 draft-ietf-oauth-assertions-02 977 o Added text about limited lifetime ATs and RTs per 978 http://www.ietf.org/mail-archive/web/oauth/current/msg08298.html. 980 o Changed the line breaks in some examples to avoid awkward 981 rendering to text format. Also removed encoded '=' padding from a 982 few examples because both known derivative specs, SAML and JWT, 983 omit the padding char in serialization/encoding. 985 o Remove section 7 on error responses and move that (somewhat 986 modified) content into subsections of section 4 broken up by 987 authn/authz per 988 http://www.ietf.org/mail-archive/web/oauth/current/msg08735.html. 990 o Rework the text about "MUST validate ... in order to establish a 991 mapping between ..." per 992 http://www.ietf.org/mail-archive/web/oauth/current/msg08872.html 993 and 994 http://www.ietf.org/mail-archive/web/oauth/current/msg08749.html. 996 o Change "The Principal MUST identify an authorized accessor. If 997 the assertion is self-issued, the Principal SHOULD be the 998 client_id" in 6.1 per 999 http://www.ietf.org/mail-archive/web/oauth/current/msg08873.html. 1001 o Update reference in 4.1 to point to 2.3 (rather than 3.2) of 1002 oauth-v2 (rather than self) 1003 http://www.ietf.org/mail-archive/web/oauth/current/msg08874.html. 1005 o Move the "Section 3 of" out of the xref to hopefully fix the link 1006 in 4.1 and remove the client_id bullet from 4.2 per 1007 http://www.ietf.org/mail-archive/web/oauth/current/msg08875.html. 1009 o Add ref to Section 3.3 of oauth-v2 for scope definition and remove 1010 some then redundant text per 1011 http://www.ietf.org/mail-archive/web/oauth/current/msg08890.html. 1013 o Change "The following format and processing rules SHOULD be 1014 applied" to "The following format and processing rules apply" in 1015 sections 6.x to remove conflicting normative qualification of 1016 other normative statements per 1017 http://www.ietf.org/mail-archive/web/oauth/current/msg08892.html. 1019 o Add text the client_id must id the client to 4.1 and remove 1020 similar text from other places per 1021 http://www.ietf.org/mail-archive/web/oauth/current/msg08893.html. 1023 o Remove the MUST from the text prior to the HTTP parameter 1024 definitions per 1025 http://www.ietf.org/mail-archive/web/oauth/current/msg08920.html. 1027 o Updated examples to use grant_type and client_assertion_type 1028 values from the OAuth SAML Assertion Profiles spec. 1030 Authors' Addresses 1032 Brian Campbell 1033 Ping Identity 1035 Email: brian.d.campbell@gmail.com 1037 Chuck Mortimore 1038 Salesforce.com 1040 Email: cmortimore@salesforce.com 1042 Michael B. Jones 1043 Microsoft 1045 Email: mbj@microsoft.com 1047 Yaron Y. Goland 1048 Microsoft 1050 Email: yarong@microsoft.com